Git provider setup

This page is for whoever runs the Diffbridge server. It enables Continue with GitHub / GitLab / Bitbucket under Connections → Add repository: members approve access on the provider's own site and pick a repository from a list, with no tokens to paste. Each provider is optional and independent. A provider you don't configure simply has no button, and the URL & access token tab keeps working for it, for self-hosted servers and for any other https remote.

These are separate OAuth apps from the sign-in ones (GITHUB_CLIENT_ID…). Sign-in only needs to read a profile; repository access can read and write code, so it uses its own app with its own scopes, and you can revoke one without touching the other.

Every callback is https://<your-domain>/api/git/oauth/<provider>/callback (if you set OAUTH_REDIRECT_BASE, that address is used instead of PUBLIC_URL). For local development use http://localhost:8080/....

#GitHub

1. Settings → Developer settings → OAuth Apps → New OAuth App (use an organization's settings to own it as an org).
2. Authorization callback URL: https://<your-domain>/api/git/oauth/github/callback.
3. Copy the Client ID → GITHUB_REPO_CLIENT_ID, generate a client secret → GITHUB_REPO_CLIENT_SECRET.

Diffbridge asks for the repo scope: GitHub OAuth apps have no narrower scope that can push to private repositories. Organizations that restrict third-party apps need an owner to approve the app once under Organization settings → Third-party access. GitHub OAuth tokens don't expire; if you enable token expiration for the app, Diffbridge refreshes them automatically.

#GitLab

1. User settings → Applications → Add new application (or a group's or the instance's Applications page).
2. Redirect URI: https://<your-domain>/api/git/oauth/gitlab/callback. Tick Confidential.
3. Scopes: read_api, read_repository, write_repository.
4. Copy the Application ID → GITLAB_CLIENT_ID and the Secret → GITLAB_CLIENT_SECRET.
5. Self-managed GitLab: also set GITLAB_BASE=https://gitlab.example.com.

GitLab access tokens last two hours; Diffbridge refreshes them automatically.

#Bitbucket Cloud

1. Workspace settings → OAuth consumers → Add consumer.
2. Callback URL: https://<your-domain>/api/git/oauth/bitbucket/callback. Leave This is a private consumer unticked.
3. Permissions: Account: Read, Repositories: Read and Write. Bitbucket takes scopes from the consumer, not from the request.
4. Copy the Key → BITBUCKET_CLIENT_ID and the Secret → BITBUCKET_CLIENT_SECRET.

Bitbucket access tokens last two hours; Diffbridge refreshes them automatically.

#Azure DevOps and everything else

There's no one-click option for Azure DevOps, Bitbucket Server or self-hosted Gitea and similar. Use URL & access token with a personal access token that can read and write code.

#What Diffbridge does with the grant

• Access and refresh tokens are encrypted with AES-256-GCM using the workspace key (and re-encrypted when the key is rotated). They are never shown in the UI, returned by the API, written to logs or put in audit entries.
• The sign-in redirect is bound to the browser that started it (a signed state, plus PKCE where the provider supports it), and only owners and admins can start it.
• A grant is sent only to its provider's own host. Repositories on other hosts can't use it.
• Several repositories can share one grant. Removing the last repository that uses it deletes the grant; to revoke access on the provider's side too, remove the app from your GitHub Authorized OAuth Apps, GitLab Applications → Authorized applications, or Bitbucket App passwords & OAuth → Authorized apps.
• Connecting and disconnecting are recorded in the audit log (git.authorize, git.connect, git.disconnect, git.deauthorize).
• If a provider revokes the grant, git operations fail with "Reconnect…". Add the repository again via Continue with….

#Environment variables