Git Sync lets a workspace use a Git repository as the source for published content. Once a repository is connected, the matching content area becomes read-only in HQ so authors do not accidentally create two competing versions of the same page.
Supported Providers
| Provider | Repository format | Setup note |
|---|---|---|
| GitHub | org/repo-name | Use a fine-grained token with read access to contents. |
| GitLab | group/project-name | Use an access token with read_repository. |
| Gitea | owner/repo-name | Enter the HTTPS API base URL for your instance, such as https://git.your-company.com/api/v1. |
Connect A Repository
- Open HQ and choose the workspace.
- Open Look & Feel, choose the Git Sources tab, and select Connect Repository.
- Choose the provider and enter the repository name, branch, content root, and optional theme root.
- Paste a personal access token with read-only repository access.
- For Gitea, enter the HTTPS API base URL. Instance roots are normalized to the provider API path.
- Save the connection and copy the webhook URL and secret shown by HQ.
Webhook Setup
Each connection shows an absolute webhook URL for the current public site, plus a one-time secret. Add that webhook in the provider dashboard, set the content type to application/json, and enable push events only.
Why the webhook URL is absolute: Git providers need a full HTTPS URL they can call from outside BulkheadOS. HQ displays the public site URL rather than a relative path or an internal dashboard route.
After Activation
- Published changes should move through Git commits for the connected content area.
- HQ shows the connection, webhook settings, latest sync status, and recent sync jobs.
- The content editor shows a read-only banner for Git-managed items, with a repository link when the provider has a universal browser URL.
- If a sync fails, review the latest job in HQ, fix the repository or token issue, and retry with a new commit or webhook event.
Security Expectations
- Use the narrowest token that can read the repository.
- Do not reuse personal tokens across workspaces or customers.
- Use HTTPS provider URLs. Local hosts and raw IP addresses are rejected for self-hosted Gitea setup.
- Rotate the token if a repository owner changes or the provider reports suspicious access.
For authoring patterns, continue to Creating Content. For the release path after content changes, see Publishing Workflow. For public discovery behavior, see AI & Discovery.