Git Sync

Keep your SpecDown docs in sync with a GitHub or GitLab repository. Every save becomes a commit; every push triggers a pull.

Connecting a Repository

1. Go to Project Settings → Git Integration.
2. Choose your provider: GitHub or GitLab.
3. Enter your repository URL (e.g. https://github.com/org/repo).
4. Generate a Personal Access Token (PAT) with repo read/write permissions.
5. Paste the PAT into the token field and click Connect.

PAT Permissions Required

How Sync Works

After connecting, SpecDown syncs your documents as follows:

• On save: SpecDown commits the document to the configured branch using the document's full_path as the file path, with a .md extension.
• On push: If your repository receives new commits, SpecDown pulls the changes and updates the corresponding documents.
• Conflict handling: Last write wins. If the same file is updated in both SpecDown and Git simultaneously, the most recent change prevails.

Branch Configuration

By default SpecDown syncs to the main branch. You can change this in Project Settings → Git Integration → Target Branch.

A typical document at path guides/api/auth is committed as:

docs/guides/api/auth.md

Commit Messages

Commits follow this format:

docs(specdown): update "Authentication Guide"

Updated via SpecDown editor
User: user@example.com
Project: my-api-docs

Webhooks (Incoming Sync)

To enable automatic pull when your repo receives pushes, set up a webhook in your Git provider pointing to:

https://specdown.app/api/webhooks/git

Set the Content-Type to application/json and use the webhook secret shown in your project settings to sign payloads.

Sync Logs

Every sync operation (push or pull) is logged in Project Settings → Git Logs. Logs include the commit SHA, timestamp, status (success / error), and any error messages.

This makes it easy to debug sync issues without leaving SpecDown.

Disconnecting

To disconnect Git sync, go to Project Settings → Git Integration and click Disconnect. Your existing documents are not affected — only future sync is stopped. The PAT is immediately deleted from the database.