---
title: "Git Sync Provider Setup"
description: "Connect GitHub, GitLab, or Gitea repositories to a BulkheadOS workspace without splitting content ownership."
canonical_url: "https://docs.bulkheados.com/content/git-sync-provider-setup/"
template: "page-node"
schema_type: "WebPage"
---

<div class="docs-content">
<p class="docs-lead">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.</p>

<h2 id="supported-providers">Supported Providers</h2>
<table>
<thead><tr><th>Provider</th><th>Repository format</th><th>Setup note</th></tr></thead>
<tbody>
<tr><td><strong>GitHub</strong></td><td><code>org/repo-name</code></td><td>Use a fine-grained token with read access to contents.</td></tr>
<tr><td><strong>GitLab</strong></td><td><code>group/project-name</code></td><td>Use an access token with <code>read_repository</code>.</td></tr>
<tr><td><strong>Gitea</strong></td><td><code>owner/repo-name</code></td><td>Enter the HTTPS API base URL for your instance, such as <code>https://git.your-company.com/api/v1</code>.</td></tr>
</tbody>
</table>

<h2 id="connect-a-repository">Connect A Repository</h2>
<ol>
<li>Open <strong>HQ</strong> and choose the workspace.</li>
<li>Open <strong>Look &amp; Feel</strong>, choose the <strong>Git Sources</strong> tab, and select <strong>Connect Repository</strong>.</li>
<li>Choose the provider and enter the repository name, branch, content root, and optional theme root.</li>
<li>Paste a personal access token with read-only repository access.</li>
<li>For Gitea, enter the HTTPS API base URL. Instance roots are normalized to the provider API path.</li>
<li>Save the connection and copy the webhook URL and secret shown by HQ.</li>
</ol>

<h2 id="webhook-setup">Webhook Setup</h2>
<p>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 <code>application/json</code>, and enable push events only.</p>

<div class="docs-callout docs-callout--info">
<p><strong>Why the webhook URL is absolute:</strong> 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.</p>
</div>

<h2 id="after-activation">After Activation</h2>
<ul>
<li>Published changes should move through Git commits for the connected content area.</li>
<li>HQ shows the connection, webhook settings, latest sync status, and recent sync jobs.</li>
<li>The content editor shows a read-only banner for Git-managed items, with a repository link when the provider has a universal browser URL.</li>
<li>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.</li>
</ul>

<h2 id="security-expectations">Security Expectations</h2>
<ul>
<li>Use the narrowest token that can read the repository.</li>
<li>Do not reuse personal tokens across workspaces or customers.</li>
<li>Use HTTPS provider URLs. Local hosts and raw IP addresses are rejected for self-hosted Gitea setup.</li>
<li>Rotate the token if a repository owner changes or the provider reports suspicious access.</li>
</ul>

<p>For authoring patterns, continue to <a href="/content/creating">Creating Content</a>. For the release path after content changes, see <a href="/content/publishing-workflow">Publishing Workflow</a>. For public discovery behavior, see <a href="/ai">AI &amp; Discovery</a>.</p>
</div>