---
title: "GitHub Instructions Source"
slug: "github-instructions-source"
updated: 2026-03-31T17:20:22Z
published: 2026-03-31T17:20:26Z
canonical: "docs.skillable.com/github-instructions-source"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

:::(Info) (Note)
When using GitHub as the instructions source, the Instructions Editor in Studio is read-only. 
:::

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**.

:::(Warning) (Warning)
Resync replaces the current instructions in Skillable with the latest version from GitHub.
:::

## Limitations
The following limitations apply when using a GitHub repository as the Instructions Source and when working with [Edit Locally](docs.skillable.com/docs/edit-locally-for-github-instructions):

**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](docs.skillable.com/docs/editing-lab-instructions-with-github-vs-studio)
* Edit instructions directly in Studio: [Editing Locally for GitHub Instructions](docs.skillable.com/docs/edit-locally-for-github-instructions)
* Resolve common issues: [Troubleshooting GitHub Instructions](docs.skillable.com/docs/troubleshooting-github-instructions)
---
{{snippet.Getting Help and Sharing Feedback}}