GitHub Instructions Source

Overview

The GitHub Instructions Source allows you to manage lab instructions using a Markdown file stored in a GitHub repository.

When configured, Skillable automatically pulls instruction content from GitHub and makes it available in the Instructions Editor and lab environments. If needed, you can manually refresh the content from the Lab Profile.

This enables a GitHub-first workflow, where:

• Instructions are authored and versioned in GitHub
• Updates are automatically synced into Skillable
• Studio reflects the latest content from your repository

This approach is best suited for teams that:

• Prefer to manage content in GitHub
• Use version control and commit history for tracking changes
• Require code review workflows before publishing updates
• Maintain instructions alongside other repository content

How It Works

Once a lab profile is connected to a GitHub repository, Skillable keeps its local copy of the instructions in sync with the configured file. Updates made in GitHub are reflected in Skillable without requiring manual intervention.

The sync follows this flow:

1. A change is committed to the instruction file in GitHub in the primary "main" branch.
2. GitHub sends a webhook event to Skillable.
3. Skillable retrieves the updated file from the repository.
4. The content is stored in Skillable's local database.
5. The next time the lab is opened, the updated instructions are displayed.

Key Behavior

• Local delivery: Labs always render from Skillable's stored copy, not directly from GitHub.
• Automatic updates: Any commit to the repositories primary branch triggers a sync, even if unrelated files change.
• Read-only editing in Studio: Instructions cannot be edited in Skillable when using this mode.

Prerequisites

Before using GitHub Instructions Source, ensure that:

• A public or private GitHub repository is available and accessible
• A Markdown (.md) file contains your lab instructions
• Repository access and authentication are configured in Skillable

Manual Resync

In addition to automatic webhook updates, you can manually pull the latest content from GitHub. Use manual resync when:

• You want to immediately retrieve recent changes
• A webhook may have been missed
• You need to refresh the local copy in Skillable

To resync:

1. Open your Lab Profile in Skillable Studio.
2. Click Edit Profile and navigate to Advanced > Instructions Sources.
3. Click Resync.

Limitations

The following limitations apply when using a GitHub repository as the Instructions Source and when working with Edit Locally:

Single file source
Only one Markdown file can be used as the instruction source for a Lab Profile. Additional files in the repository are imported but not managed by Skillable.

No asset synchronization
When using Edit Locally, any new media added to your instructions must be uploaded to GitHub separately. If not, the Pull Request will contain broken references, even if the content still renders correctly in the lab environment.

Rendering differences in GitHub
Some Skillable-specific Markdown elements (such as knowledge blocks, alerts, and tokens) don't render correctly in GitHub previews. However, these elements will display properly in the lab environment.

This is expected behavior and applies to all GitHub-based instruction sources. GitHub reviewers should be aware that the rendered view in GitHub doesn't reflect the in-lab experience.

Repository size limit
The total size of the GitHub repository cannot exceed 500 MB. If this limit is reached, synchronization will stop until the repository size is reduced.

To avoid this issue:

• Keep repositories focused on lab content
• Split large repositories before approaching the limit

Pull Request-only workflow
Skillable always creates a Pull Request when syncing changes. Direct commits to the configured primary branch aren't supported.

All changes must be reviewed and merged in GitHub.

Summary

The GitHub Instructions Source enables a GitHub-first approach to managing lab instructions, with updates automatically reflected in Skillable.

By connecting a repository and configuring a Markdown file, you can:

• Author and version instructions in GitHub
• Keep lab content synchronized automatically
• Maintain a consistent, reviewable workflow outside of Studio.

This approach provides strong version control and collaboration benefits. For teams that need more flexibility when working in Studio, see Edit Locally for GitHub Instructions

Next Steps

• Learn how the supported editing workflows differ: Editing Lab Instructions with GitHub vs. Studio
• Edit instructions directly in Studio: Editing Locally for GitHub Instructions
• Resolve common issues: Troubleshooting GitHub Instructions