Connect a Git provider

Git synchronization connects GitHub.com, GitLab.com and Bitbucket Cloud to a specific Localisync content branch. An operator must register the provider applications before workspace managers can connect. Self-hosted Git services and command-line synchronization are outside this integration.

Live acceptance with all three provider accounts is pending. Local tests do not establish that your application’s provider permissions or callback configuration are correct.

Operator registration

Use the HTTPS origin of your panel in the following paths. Do not enter credentials in documentation, chat, Git, container images or build arguments. Use private runtime files with permissions restricted to the appropriate service identity.

Provider	Callback path	Webhook path	Required setup
GitHub App	/api/git/callback/github	/api/git/webhooks/github	Repository Contents and Pull requests: read/write; Metadata: read. Subscribe to push and pull request events. Enable expiring user access tokens and install the app only on selected repositories.
GitLab OAuth	/api/git/callback/gitlab	/api/git/webhooks/gitlab	Confidential OAuth application with api scope. The authorizing account needs Maintainer access to configure project hooks. PKCE S256 binds the code exchange.
Bitbucket OAuth consumer	/api/git/callback/bitbucket	/api/git/webhooks/bitbucket	Account read, repository write, pull request write and webhook management permissions.

GitHub authorization uses the App’s user authorization flow and only discovers repositories available through App installations. Install the App before clicking Connect GitHub. No repository code is cloned or executed.

For GitLab, use a signing token with the whsec_ prefix and a random base64-encoded secret of at least 32 bytes. The integration requires Standard Webhooks raw-body signatures; it does not fall back to the older plaintext X-Gitlab-Token header. GitHub and Bitbucket use independent random webhook secrets of at least 32 bytes. GitLab and Bitbucket project hooks are registered when the worker first prepares a mapping preview.

Consult the official GitHub App permissions, GitLab OAuth scopes, GitLab signing tokens and Bitbucket OAuth permissions during registration.

Register the three applications

Use separate registrations and disposable repositories for acceptance. Keep production repositories out of their initial scope. A local loopback panel URL cannot receive provider webhooks; configure an operator-approved HTTPS test panel origin before the live run. Creating registrations does not deploy this feature.

GitHub.com

1. Open the owning account or organization’s Settings → Developer settings → GitHub Apps → New GitHub App.
2. Enter an application name and your panel’s HTTPS homepage. Set the user authorization callback to the GitHub callback path above, including the panel origin.
3. Enable expiring user authorization tokens. Set the webhook URL and a newly generated webhook secret; configure the repository permissions and events in the table.
4. Save the Client ID and create an OAuth client secret. This integration uses GitHub App user authorization; it does not need a personal access token or an App private key.
5. Install the App on the isolated test repository only. The connecting Localisync manager must also have provider access to that repository.

GitLab.com

1. Open the appropriate account/group application settings and add a confidential OAuth application.
2. Enter the GitLab callback URL, select the api scope and save the registration.
3. Save the application ID and secret into the private runtime configuration. Do not paste them into a workspace form or a ticket.
4. Prepare a separate whsec_ signing secret as described above. The worker registers the project hook; the connecting account needs Maintainer access to the disposable project.

Bitbucket Cloud

1. Open the workspace settings and create an OAuth consumer.
2. Set its callback URL to the Bitbucket callback above. Configure the permissions in the table and keep the consumer confidential.
3. Save the consumer key as clientId and its secret in the private secret file.
4. Create a separate random webhook secret. The connecting account must be able to write the disposable repository, create pull requests and manage its hooks.

For all three providers, the client secret and webhook secret are different values. Never reuse a production repository token as an application secret. A successful provider registration is only preparation; complete the isolated acceptance checklist below before enabling customer mappings.

Private configuration

GIT_PROVIDERS_CONFIG_FILE points to a JSON file. Only include configured providers. Each entry contains clientId, secretFile and webhookSecretFile. The file paths are absolute paths inside the process/container. The secret file contains the OAuth client secret; the webhook file contains that provider’s webhook secret. Do not put secret contents directly in the JSON.

Both API and Git worker need the provider configuration. The API needs webhook secrets; only the Git worker needs the client-secret files for code exchange and token refresh. Mount only the files needed by each process. An omitted provider is shown as requiring operator setup, rather than pretending the connection is available.

For example, this configuration contains paths and public client IDs only. Replace the marked IDs and mount each referenced secret file privately. Omit providers that are not configured.

{
  "github": {
    "clientId": "REPLACE_WITH_GITHUB_APP_CLIENT_ID",
    "secretFile": "/run/localisync/git-providers/github-client-secret",
    "webhookSecretFile": "/run/localisync/git-providers/github-webhook-secret"
  },
  "gitlab": {
    "clientId": "REPLACE_WITH_GITLAB_APPLICATION_ID",
    "secretFile": "/run/localisync/git-providers/gitlab-client-secret",
    "webhookSecretFile": "/run/localisync/git-providers/gitlab-webhook-secret"
  },
  "bitbucket": {
    "clientId": "REPLACE_WITH_BITBUCKET_CONSUMER_KEY",
    "secretFile": "/run/localisync/git-providers/bitbucket-client-secret",
    "webhookSecretFile": "/run/localisync/git-providers/bitbucket-webhook-secret"
  }
}

The worker and API use separate GIT_VAULT_CONFIG_FILE files with url, caFile, roleIdFile and secretIdFile. url must be HTTPS with a valid certificate chain. Git credentials use the dedicated derived Transit key git-connections. API policy allows encryption; worker policy allows encryption and decryption. Translation-assistance policies are unchanged.

The pnpm git:vault operator command provisions this separate key and policies against an already initialized, unsealed persistent vault. Supply a private, short-lived operator token using GIT_VAULT_BOOTSTRAP_TOKEN_FILE, plus GIT_VAULT_ORIGIN, GIT_VAULT_CA_FILE and a new GIT_DIRECTORY. It creates private API/worker AppRole files. Revoke the provisioning token afterwards; never mount it in either service. Preserve the separate vault recovery material. The provisioner refuses existing output directories, keys, policies and AppRoles. If provisioning fails partway through, retain the private output, inspect the created resources with the operator identity and revoke unused credentials before a reviewed repair. Do not delete or overwrite the Transit key to retry setup.

Migrate and start

Stop incompatible writers and take a verified backup before applying migrations. Run pnpm db:migrate and pnpm db:queue as separate deployment steps with their existing restricted migration identities. Application startup does not run migrations.

The Git worker has its own localisync-git queue. For local processes, configure the existing environment and run pnpm dev:git. pnpm start:git uses the compiled worker. compose.git.yaml adds the Git worker to the existing PostgreSQL and vault Compose networks; it expects private runtime mounts and does not provision a production installation. Build the git-worker Docker target from apps/api/Dockerfile when deploying containers.

Use /health/live and /health/ready on the private Git worker listener (default loopback port 4014). Provider/vault failures do not make independent translation delivery unavailable. Set the shared LOCALISYNC_MAINTENANCE_DIR for both API and worker; add git-worker to the backup participant inventory. Include Git AppRole/configuration files and operator provider secrets in the encrypted private configuration inventory. The existing Raft snapshot contains the separate Transit key.

Upgrade, rollback and recovery

Apply the additive Git migrations and queue migration with the Git worker stopped. Start the API/panel and worker from the same reviewed build. Verify private worker readiness, its localisync_worker_heartbeat_seconds{queue="git"} metric, the provider catalog and a disposable repository before allowing customer connections.

For rollback, pause mappings, stop the Git worker at its graceful boundary and return API/panel to the previous compatible build. Retain the Git tables, Transit key and encrypted credentials. Do not run a destructive down migration, delete remote branches or close pull requests automatically. Inspect operations left in sending/outcome_unknown against the provider; a process restart is not proof that a remote write did not happen.

A restored database quarantines grants and mappings. Reconnect using an authorized manager, inspect surviving remote requests and then explicitly resume the mapping. Keep the restored worker behind the maintenance recovery barrier until operator reconciliation is complete. An existing remote commit or merge is never rolled back by a database restore.

Connect a workspace

1. An Owner or Admin opens Git connections for the workspace.
2. Review the provider permissions and click Connect.
3. Authorize using the intended provider account. The callback must return to the same signed-in Localisync manager.
4. Wait for connected. Code exchange happens in the Git worker.
5. Open the selected project branch’s Git synchronization page and connect repository files.

Reconnect preserves mapping identity while replacing authorization. Previous approvals become stale. Disabling a connection stops subsequent operations but does not revoke the provider’s own authorization; revoke that separately in the provider account when needed.

Isolated provider acceptance

For each provider, use a disposable repository with two translation files and no customer content. Verify connection, discovery, a reviewed import, a panel edit, PR/MR creation, provider-side merge and verified target content. Repeat with a manually changed/closed PR, revoked access, an invalid webhook signature and a delivery replay. Record provider configuration and actual results without tokens or translation bodies. Never use the public SDK release repository for these write tests.