Overview
Lab Profiles configured with a GitHub repository as their Instructions Source are read-only in Studio by default. All changes are made in GitHub, and Skillable automatically pulls updates via webhook.
Edit Locally introduces a second workflow that allows you to:
- Edit instructions directly in the Studio Instructions Editor
- Save changes immediately in Skillable
- Push updates to GitHub as a Pull Request (PR)
This feature is optional and can be enabled per Lab Profile. It does not replace the default GitHub-based workflow.
Edit Locally applies to a single Markdown file configured on the Lab Profile. It does not sync images or additional repository assets.
Edit Locally is useful when:
- You want to write or edit content directly in Studio
- You need to quickly update instructions without switching tools
- Your team uses GitHub for review, but not for authoring
- Contributors don't have direct access to GitHub
- You need to update live lab content immediately
Use Cases
Edit Locally is designed to support flexible authoring workflows across different teams.
Write in Studio, review in GitHub. Author instructions in Skillable, then use GitHub PRs for review and approval.
Reduce context switching. Make quick updates without leaving Studio or opening a GitHub editor.
Support mixed contributor workflows. Allow some contributors to work in GitHub while others work in Studio.
Handle limited GitHub access. Edit content in Studio and hand off the PR to someone with GitHub permissions to merge.
Make fast updates to active labs. Update instructions immediately in Skillable, then sync those changes back to GitHub afterward.
Editing Modes: GitHub (Default) vs. Edit Locally
| Default | Edit Locally | |
|---|---|---|
| Studio editing | Read-only | Fully editable |
| How content updates | GitHub webhook trigger or manual resync | Edit in Studio, manually sync via PR, or manual resync |
| GitHub webhooks | Active; updates are applied automatically | Still received, but does not overwrite local edits |
| Who owns merge decisions | N/A | GitHub (PR must be reviewed and merged) |
| Opt-in required | No (default behavior) | Yes, per Lab Profile |
| Lab delivery | From Skillable's local copy | From Skillable's local copy |
Switching back from Edit Locally without first syncing your changes will permanently discard any local edits in Skillable Studio. The system prompts you to confirm this action.
Choosing the Right User Flow
| Scenario | Recommended User Flow / Mode |
|---|---|
| Team edits in GitHub, Studio is read-only | Default (Edit Locally OFF) |
| Author wants to edit in Studio and review in GitHub | Edit Locally ON |
| Quick iteration on live lab content | Edit Locally ON |
| Applying a hotfix to GitHub-based content | Edit Locally ON → Sync → Merge |
| Reverting to the latest GitHub version | Edit Locally OFF (automatically resyncs) or Manual Resync |
Configure Edit Locally
Prerequisites
This article covers Edit Locally only. If you have not yet connected to a GitHub repository, see our GitHub Repository article.
Before using Edit Locally, confirm:
- Instructions Source is set to GitHub Repository. Edit the Lab Profile and navigate to Advanced > Instructions Source.
- GitHub configuration is complete (repository, branch, content file, and authentication are all valid).
- Configuration Complete = Yes in the Instructions Source details.
Enabling Edit Locally
To enable Edit Locally:
- Open the Lab Profile in Studio.
- Click Edit Profile and navigate to the Advanced tab.
- In the Instructions Source section, toggle Edit Locally to Yes.
The Edit Locally toggle is only visible when GitHub is configured as the Instructions Source.
If you disable Edit Locally while unsynced edits exist:
- Local changes are permanently discarded
- The lab resyncs with the latest GitHub version
This action cannot be reversed. Always sync your changes first.
Once Edit Locally is enabled, the Instructions Editor becomes fully writable.
Key behaviors:
- Changes are saved server-side, not in your browser.
- Labs update immediately, no GitHub interaction required.
- Sync Changes becomes available when edits are detected.
- Autosave is enabled and recommended.
The editor banner still indicates the lab uses an external Instructions Source. This is expected.
How Sync Changes Works
When you're ready to push updates to GitHub:
- Click Sync Changes in the Instructions Editor.
The Sync Changes to External Instruction Source dialog opens.
- Fill in the Pull Request details:
- Change Title (required): Enter a clear, descriptive title up to 100 characters. This becomes the Pull Request title in GitHub.
- Change Description (optional): Describe what changed and why, up to 10,000 characters. This becomes the top of the PR body in GitHub.
- Click Sync Changes to create a Pull Request.
A new branch is created, the instruction file updates are committed, and a Pull Request is opened in GitHub.
Skillable does not manage the PR after creation. All review and merge actions occur in GitHub. Everything else (branch name, commit message, committer identity, and the PR body footer) is managed automatically by Skillable.
If PR creation fails after the branch was created, Skillable automatically removes the temporary branch from GitHub to keep the repository clean.
Clicking Cancel within the dialog does not discard local edits. Your content remains saved in Skillable until you are ready to sync.
Merging Changes in GitHub
After syncing, a Pull Request is opened in your GitHub repository. To complete the sync workflow:
- Open the Pull Request in GitHub. You can use the PR link in the Sync Changes dialog or open your GitHub repository's Pull Requests tab.
- Review the changes in the Files changed tab.
Note the auto-generated branch name in the PR header. The timestamp indicates when the sync occurred. - Approve and Merge the PR using your team's standard workflow.
After merging:
- GitHub contains the updated version
- Skillable continues using the local copy
To return to GitHub-driven updates, disable Edit Locally or force a manual resync.
Reverting to the GitHub Version
If you need to discard local edits and return to the version stored in GitHub, you can manually refresh the instructions using Resync.
The Resync button is available in the Instructions Source section of the Lab Profile. It allows you to pull the latest version of the instruction file from GitHub outside of the normal webhook cycle.
When to Use Resync
- You merged updates from GitHub and want to pull them into Skillable immediately.
- You believe the local Skillable copy is out of date (e.g., a webhook was missed).
- You want to discard local edits and restore the GitHub version.
Resync replaces Skillable's local instruction content with the current version in GitHub. Any unsynced local edits will be permanently lost. Use this action with caution.
How to Resync
- Open the Lab Profile.
- Click Edit Profile and navigate to Advanced > Instructions Source.
- Click Resync next to the last sync timestamp.
- Confirm when prompted.
After a successful resync, the Last Sync Time and Last Synced By fields are updated. The Last Synced By value shows Manual User Resync.
Summary
Edit Locally allows you to edit lab instructions directly in Studio while maintaining GitHub as the system of record.
Use Studio to make and preview changes quickly. Use GitHub to review and merge updates through Pull Requests. Sync changes before switching modes to avoid data loss.
References
Sync Changes to External Instruction Source States
When you click Sync Changes, a dialog opens. The tables below describe its possible states and the messages displayed in each state:
| State | What You See |
|---|---|
| Idle | Form fields are available; the Sync Changes button is active. |
| Submitting | A loading indicator is displayed; the Sync Changes button is disabled. |
| Success | A confirmation message appears with a link to the newly created PR in GitHub and repository. |
| Failure | A stage-specific error message appears (see below), along with a Retry button. Form data and local edits are preserved. |
Failure messages by stage:
| Stage | Message |
|---|---|
| Initial (pre-branch) | An error occurred while preparing to create the pull request. No changes were made to the repository. |
| Creating branch | Unable to prepare a branch for your changes. No changes were made to the repository. |
| Committing changes | Your changes could not be saved to the repository. The temporary branch is being removed. |
| Creating PR (after commit) | Your changes were saved but the pull request could not be created. The temporary branch is being removed. |
How Sync Changes Work
When you click Sync Changes, Skillable:
- Creates a new branch from the configured primary branch.
- Commits the instruction file updates to the new branch.
- Opens a Pull Request in GitHub.
Additional details:
- The branch names are auto-generated using a timestamp-based format (e.g.,
skillable/instructions-sync-20260313-014231). - Commit messages follow Conventional Commits format.
- Commits use a service-level identity (not the Studio user).
- A standardized footer is added to the PR description, including links back to Skillable.
Summary of Key Behaviors
The following behaviors provide additional context for how Edit Locally works. These details aren't required for typical use but may be helpful when troubleshooting or reviewing GitHub activity.
| Behavior | Detail |
|---|---|
| Edit Locally is per Lab Profile | Enabling it on one lab does not affect others |
| Webhook updates are blocked while Edit Locally is on | GitHub commits do not overwrite local Studio edits |
| Lab delivery uses Skillable's local copy | Learners are unaffected by sync direction or mode |
| PR creation is required | Direct commits to the primary branch are not supported |
| PR status is not tracked by Skillable | All merge and review actions occur in GitHub |
| Local edits are resilient | Changes are stored server-side and persist across sessions |
| Sync Changes state is evaluated at initial page load | Any edit made after page load guarantees the button is enabled |
| Disabling Edit Locally without syncing is destructive | Unsynced edits are permanently lost |
| Orphaned branches are automatically cleaned up | Failed PR sync attempts remove temporary branches |
| Commits use a service identity | The Studio user is not recorded as the commit author |
Related Resources
- GitHub Instructions Source
- GitHub Repository
- Editing Lab Instructions with GitHub vs. Studio
- Troubleshooting GitHub Instructions
If you’re experiencing an issue with a lab, platform feature, or your account, please submit a ticket to Skillable Support. Our Support team can help you troubleshoot errors, resolve access issues, and answer questions specific to your environment.
If you noticed an error or have suggestions for improving this documentation, use the Was this article helpful? section below. Your input helps us keep our documentation accurate and up to date.
Was this article helpful?
Please note that this feedback is for documentation only. Be sure to log in to your Skillable account when leaving feedback so we can respond directly.