---
title: "Editing Locally for GitHub Instructions"
slug: "edit-locally-for-github-instructions"
updated: 2026-03-31T17:20:11Z
published: 2026-03-31T17:20:11Z
canonical: "docs.skillable.com/edit-locally-for-github-instructions"
---

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

# Editing Locally for GitHub Instructions

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

:::(Info) (Scope)
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 |


:::(Warning) (Important)
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
:::(Info) (New to GitHub repository as an Instruction Source?)
This article covers Edit Locally only. If you have not yet connected to a GitHub repository, see our [GitHub Repository](https://docs.skillable.com/docs/github-repository) article.
:::

Before using Edit Locally, confirm:

1. **Instructions Source is set to GitHub Repository**. Edit the Lab Profile and navigate to **Advanced** > **Instructions Source**. 
2. **GitHub configuration is complete** (repository, branch, content file, and authentication are all valid).
3. **Configuration Complete = Yes** in the Instructions Source details.

![instructions-source-config.png](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/instructions-source-config.png){height="250" width=""}

## Enabling Edit Locally
To enable Edit Locally:

1. Open the **Lab Profile** in Studio.
2. Click **Edit Profile** and navigate to the **Advanced** tab.
3. 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.

:::(Warning) (Disabling Edit Locally)
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. 

![edit-locally-warning.png](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/edit-locally-warning.png){height="100" width=""}
:::

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.

:::(Info) (Note)
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:

1. Click **Sync Changes** in the Instructions Editor.
    The **Sync Changes to External Instruction Source** dialog opens.
![sync-changes-modal.png](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/sync-changes-modal.png){height="150" width=""}
2. Fill in the Pull Request details:
    1. **Change Title** (required): Enter a clear, descriptive title up to 100 characters. This becomes the Pull Request title in GitHub.
    2. **Change Description** (optional): Describe what changed and why, up to 10,000 characters. This becomes the top of the PR body in GitHub.
3. 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:

1. 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.
3. 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.
5. 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.

:::(Warning) (Warning)
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
1. Open the Lab Profile.
2. Click **Edit Profile** and navigate to **Advanced** > **Instructions Source**.
3. Click **Resync** next to the last sync timestamp.
4. 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`.

:::(Internal) (Internal only)
## Internal Notes: App Settings

The following fields are all **app settings** on the External Instruction Sync service. They can be changed at any time without a code deployment or restart. Changes take effect on the next PR creation.

### Branch Name Template

**App setting key:** `AppSettings:PRBranchNameTemplate`  
**Default value:** `skillable/instructions-sync-{Year}{Month}{Day}-{Hour}{Minute}{Second}`

The branch name template supports the following tokens:

| Token | Description | Example output |
|---|---|---|
| `{Year}` | 4-digit UTC year | `2026` |
| `{Month}` | 2-digit UTC month | `03` |
| `{Day}` | 2-digit UTC day | `13` |
| `{Hour}` | 2-digit UTC hour (24h) | `01` |
| `{Minute}` | 2-digit UTC minute | `42` |
| `{Second}` | 2-digit UTC second | `31` |
| `{Lab Profile Id}` | Numeric ID of the lab profile | `9876` |
| `{Instructions Set Id}` | Numeric ID of the instruction set | `1234` |

**Example templates:**

| Template | Resulting branch |
|---|---|
| `skillable/instructions-sync-{Year}{Month}{Day}-{Hour}{Minute}{Second}` *(default)* | `skillable/instructions-sync-20260313-014231` |
| `lod/{Lab Profile Id}/sync-{Year}{Month}{Day}` | `lod/9876/sync-20260313` |
| `lp-{Lab Profile Id}/is-{Instructions Set Id}` | `lp-9876/is-1234` |

Tokens can be combined in any order. If the template is empty or not set, the default is used.

---

### Commit Message

**App setting key:** `AppSettings:GitHubPRSyncCommitMessage`  
**Default value:** `chore(instructions): sync changes from Skillable Instructions Editor`

The commit message follows [Conventional Commits](https://www.conventionalcommits.org/) format. It is applied to every commit made by the sync service and can be changed to match your team's commit message standards without a code change.

---

### Committer Name

**App setting key:** `AppSettings:GitHubCommitterName`  
**Default value:** `Skillable Instructions Sync`

This is the display name attributed to the commit in GitHub. It is a service-level identity, not the individual Studio author's account. Changing this does not require a code deployment.

---

### Committer Email

**App setting key:** `AppSettings:GitHubCommitterEmail`  
**Default value:** `support@skillable.com`

This is the email address attributed to the commit in GitHub. Update this to match a recognized service account or support alias for your organization.

---

### Branded Badges in PR Body

Every PR body automatically includes a **Skillable PR Details** footer section appended by the system. This section includes:

- Attribution text identifying the PR's origin in Skillable.
- An **Edit In Skillable Studio** badge (purple — `#7000ff`) that links directly to the Instructions Editor for the lab.
- A **View Lab Profile** badge (green — `#136945`) that links to the lab profile details page.

The badge links are generated dynamically using the configured `AdminServiceUrl`. The badge image format is shields.io-based markdown. This footer cannot be disabled per-PR — it is a platform-level behavior on all PRs created through this feature.

Example auto-appended footer:

```markdown
---

### Skillable PR Details
This PR was created from the Skillable Instruction Editor.
The links below provide helpful context and are used for tracking and support.

- This PR was automatically created from the Skillable Instruction Editor.
- [![Edit in Skillable Studio](https://img.shields.io/badge/Edit%20In-Skillable%20Studio-7000ff)](https://studio.skillable.com/Instructions/Edit/9876?instructionsSetId=1234)
- [![View Lab Profile](https://img.shields.io/badge/View-Lab%20Profile-136945)](https://studio.skillable.com/LabProfile/Details/9876)
```
:::
---
## 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:

1. **Creates a new branch** from the configured primary branch. 
2. **Commits the instruction file updates** to the new branch. 
3. **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](https://www.conventionalcommits.org/) 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.

![github-pr-example.png](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/github-pr-example.png){height="250" width=""}


### 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](docs.skillable.com/docs/github-instructions-source)
- [GitHub Repository](https://docs.skillable.com/docs/github-repository)
- [Editing Lab Instructions with GitHub vs. Studio](docs.skillable.com/docs/editing-lab-instructions-with-github-vs-studio)
- [Troubleshooting GitHub Instructions](docs.skillable.com/docs/troubleshooting-github-instructions)

---
{{snippet.Getting Help and Sharing Feedback}}