Using GitLab as an Instruction Source

Skillable supports using external instruction sources from public repositories. When using GitLab as an external instruction source, you must configure specific settings within GitLab. This article walks you through that configuration process.

External Management Advantages

Using an external instruction source provides several advantages when developing and maintaining lab content:

1. Offline editing: External instruction management allows you to create and edit content in structured Markdown files. You can work offline using any standard Markdown editor available for Windows, macOS, Linux, iOS, or Android.
2. Revision control: GitLab natively supports revision control, enabling you to compare versions, roll back changes, and view detailed commit history for any lab content configured with an external source.
3. Multi-author support: Using an external instruction source enables multiple authors to collaborate on content for the same lab simultaneously.

External Management Disadvantages

Skillable Studio custom syntax is unavailable externally. Skillable-specific Markdown doesn't render in external repositories, though it still renders correctly inside a lab.

Elements that are unknown or unsupported externally include:

• Knowledge block/link
• Alert block/link
• Help block/link
• Hint block/link
• Note block
• Copyable text
• Type text
• code block modifiers
• @lab replacement tokens/Intellisense

Best Practices

When using an external instruction source, follow these best practices to ensure your content remains organized, performant, and easy to maintain:

• Keep your repository as small as possible to avoid performance issues like slow load times.
• Use repositories dedicated to lab content, and avoid mixing unrelated content.
• A single repository can host instructions for multiple lab profiles. We recommend one Markdown source per course or lab series.
• If your instructions span multiple pages, create separate Markdown files and include them individually in the Skillable instruction set.

Prerequisites

Before working with GitLab in Skillable, ensure the following tasks are completed in GitLab:

1. You have a GitLab account.
2. A project is created for storing the instruction content.
3. CI/CD is enabled on the project:
   Settings > General > Visibility, Project features, Permissions > Repository > CI/CD.
4. Project visibility is set to Public Access:
   Settings > General > Visibility, Project features, Permissions > Project visibility.
   See GitLab's Project and group visibility documentation for more details.
5. GitLab Pages is enabled with Everyone to have Access:
   Settings > General > Visibility, Project features, Permissions > Pages.
6. Your Markdown files are created in GitLab.

Configure GitLab for External Instruction Sources

Getting Started with GitLab

To allow Skillable to access Markdown files stored in GitLab, the files must be published through GitLab Pages, which provides static hosting accessible from external systems. After configuration, every commit to the repository triggers a pipeline that processes and republishes the files to GitLab Pages.

You can monitor the pipeline under Build > Pipelines, which also provides diagnostic information for troubleshooting.

In the project repository, create a file named .gitlab-ci.yml. This file defines the CI/CD job that processes the Markdown files and publishes them to GitLab Pages. A sample directory structure and the YAML file contents are shown below:

This configuration copies all files matching the pattern BuildingWebsites-P???.md into the public folder, which GitLab Pages uses for publishing. The wildcard pattern ensures you do not need to specify individual filenames.

pages:
  stage: deploy
  script:
    - mkdir public
    - cp BuildingWebsites-P???.md public/
  artifacts:
    paths:
      - public
  only:
    - main

After committing changes to the main branch, monitor the publishing pipeline under Build > Pipelines.

Configuring the Instruction Set in a Lab Profile

To configure a lab profile to use instructions from an external GitLab source:

1. From Skillable Studio, open the lab profile and select Edit Instructions in the upper-right corner.
2. Select an instruction set.
3. Add the markdown-include syntax:
   !instructions\[](url).
   Replace url with the GitLab Pages URL for your Markdown file. For example:
   !instructions\[](https://instruction-include-d03b90.gitlab.io/lab001.md). The root GitLab Pages URL is located in the project under Deploy > Pages.

After saving, the Markdown content appears in the lab. Confirm the instructions display correctly. If updates are required, edit the content in the external repository. Due to caching, updates may take a few minutes to appear in Skillable.

You can also add content to the lab instructions directly in Skillable Studio using the Instructions Editor.

Using Activities with External Sources

Labs that use an external instruction source can still use automated, question-based, and AI Vision activities. Activities must be created in the lab profile and added to the external repository's lab instructions.

To add an activity to a lab profile with instructions from an external GitLab source:

1. From Skillable Studio, open the lab profile and select Edit Instructions in the upper-right corner.

2. Open the Activities menu.

3. Select the activity type: + New Question, + New Automated Activity, or + New AI Vision Activity.

4. Create the activity.

5. After creating the activity, copy its token.

6. Navigate to your external repository and open the Makrkdown file used for lab instructions.

7. Paste the token into the file where you want the activity to appear.

   Repeat these steps to add more activities.

Summary

Using GitLab as an external instruction source gives you a flexible and scalable way to manage lab content. By configuring GitLab Pages, enabling CI/CD, and publishing your Markdown files through a simple pipeline, you can maintain version-controlled, collaboratively authored instructions that Skillable can reliably consume. Although Skillable-specific Markdown elements do not render in GitLab, they are fully supported when the content displays in a lab. You can also integrate Skillable activities by adding their tokens directly to your external Markdown. Following the recommended best practices—such as keeping repositories focused and organized—helps ensure consistent performance and easier long-term maintenance of your lab instructions.