Branching
Branches let you make changes to your documentation without affecting the live site. Each branch is a copy-on-write snapshot of your main content. Edit freely on a branch, preview the result, then publish when ready.
How branches work
When you create a branch, Skrypt copies every file from main into the branch. From that point forward, edits on the branch are isolated. Your live site continues serving the main content until you explicitly publish the branch.
Branches are stored in the doc_branches table with their files in doc_branch_files. Each branch tracks which files were added, modified, or deleted relative to main.
Creating a branch
From your project dashboard, click New Branch and enter a name.
Branch names follow these rules:
| Rule | Example |
|---|---|
| Lowercase letters, numbers, hyphens, underscores, slashes | fix-typos, v2/api-docs |
| Max 100 characters | -- |
Cannot be named main | -- |
| Must be unique within the project | -- |
Spaces are automatically converted to hyphens. Skrypt rejects duplicate names with a 409 Conflict error.
Editing on a branch
Switch to a branch using the branch selector in the editor toolbar. All edits you make while a branch is active apply only to that branch.
You can:
- Edit existing files
- Create new files
- Delete files (marked as deleted, applied on publish)
Changes are saved to the branch immediately. Switch back to main at any time to see the current live content.
Preview deploys
Each branch gets a preview deployment so you can see your changes rendered before publishing. The preview URL follows this pattern:
https://{slug}--{branch-name}.skrypthq.dev
Preview deploys update automatically when you save changes on the branch.
Publishing
Publishing merges a branch into main and deploys the result to your live site.
Click Publish on the branch, or call the publish API:
curl -X POST https://app.skrypt.sh/api/projects/{slug}/publish \
-H "Content-Type: application/json" \
-d '{"branchId": "your-branch-id"}'
The publish process:
- Validates the branch belongs to your project
- Applies all branch file changes to main (upserts and deletes)
- Deploys the updated main content to Cloudflare Pages
- Deletes the branch and its files (cascade)
If the merge fails, the branch is preserved so you can retry. The branch is only deleted after a successful merge.
You can also publish main directly (without a branch) by calling the publish endpoint with no branchId.
Deleting branches
Delete a branch from the dashboard or via the API:
curl -X DELETE "https://app.skrypt.sh/api/projects/{slug}/branches?id={branch-id}"
Deleting a branch removes all branch files (cascade delete). This cannot be undone. If you want to keep the changes, publish the branch first.
Plan limits
Branch creation counts against your generation quota:
| Plan | Branch creation |
|---|---|
| Free | Included in your 1 generation/month |
| Pro | Unlimited |