Connect a Git repository

deploybase clones your repository at build time. It needs read access, and if you want pushes to deploy themselves, permission to register a webhook.

There are three ways to grant that, in descending order of how little you have to think about it.

GitHub: install the App

Press Connect GitHub in the project wizard, install the deploybase App, and pick which repositories it may see.

There is no token to create and no scope to reason about. Builds authenticate with a short-lived installation token, held in memory until shortly before it expires and never written down. The connection belongs to the team, so it covers every GitHub project you create afterwards, and it includes webhook access, so auto-deploy and pull request previews work with nothing more to configure.

Revoke it from GitHub at any time, or narrow which repositories it sees from Adjust GitHub App access in the repository picker.

A GitHub project can still use a token instead if you prefer. When a project has one, it takes precedence over the App.

Forgejo 16 and later: connect without storing anything

On Forgejo 16.0 and later, including Codeberg, deploybase can authenticate without holding a credential at all. It signs a short-lived token per operation, and your instance verifies the signature against a public key we publish. Nothing long-lived exists on our side to leak.

When you paste a Forgejo URL we check what your instance supports and offer Connect without a stored token when it is available. Gitea and Forgejo before 16.0 do not have the feature, and the option stays hidden.

Setup takes one round trip, because Forgejo only reveals the audience value after you save:

1. In Forgejo, open Settings → Authorized Integrations and add one of type Generic JWT
2. Set the issuer to https://api.deploybase.eu
3. Grant read:repository, plus write:repository if you want auto-deploy, and restrict it to the one repository
4. Paste in the claim rules deploybase shows you. They pin the integration to that repository and to your deploybase account
5. Save, then copy the Audience Forgejo generated back into deploybase

Keep the audience to yourself. The claim rules are what make it safe to hold, but there is no reason to publish it.

This is the only way to get least-privilege auto-deploy on Forgejo, because the permissions live on the integration rather than on an account-wide token. Granting write:repository here does not expose your other repositories.

Everywhere else: an access token

Paste an HTTPS clone URL and, for a private repository, a token with read permission. We store it encrypted, use it only during git clone, and never write it to a build log.

SSH URLs are not supported.

Provider	Clone URL	Credential
GitHub	https://github.com/you/repo.git	Personal access token, classic or fine-grained
GitLab	https://gitlab.com/you/repo.git	Project, group, personal or fine-grained access token, or a deploy token with its username
Bitbucket	https://bitbucket.org/you/repo.git	App password
Codeberg, Forgejo, Gitea	https://codeberg.org/you/repo.git	Access token

Scopes for cloning

Provider	Token	Permission
GitHub	Fine-grained	Contents: Read on the repository
GitHub	Classic	repo, or public_repo for a public one
GitLab	Project, group or personal access token	read_repository (read_api also works)
GitLab	Fine-grained personal access token	Code: Download
GitLab	Deploy token	read_repository, sent with the token’s username
Bitbucket	App password	Repositories: Read
Codeberg, Forgejo	Access token	read:repository

Extra scopes for auto-deploy

Auto-deploy registers a webhook, which most providers treat as an administrative action on the repository:

Provider	Token	Additional permission
GitHub	Fine-grained	Webhooks: Read & write
GitHub	Classic	Already covered by repo
GitLab	Project, group or personal access token	api, and the Maintainer role on the project
GitLab	Fine-grained personal access token	Webhook: Create, and the Maintainer role on the project
GitLab	Deploy token	Not possible. GitLab’s API does not accept deploy tokens
Bitbucket	App password	Webhooks: Read and write
Codeberg, Forgejo	Access token	write:repository, not restricted to specific repositories

Without these, validation still passes and the clone still works. The webhook registration is what fails, when you switch auto-deploy on.

On Forgejo, a repository-scoped token cannot do auto-deploy

Forgejo 15.0 added repository-specific tokens, and Codeberg runs a newer release than that. Restricting a token to one repository is enough to clone it, and it is the right choice for a read-only connection.

It is not enough for webhooks. Forgejo treats webhook management as a repository-admin operation, and repository-scoped tokens cannot perform repository-admin operations. That leaves a real choice:

• Least privilege, no auto-deploy. A read:repository token scoped to the one repository. Deploy from the dashboard, the CLI, or the API
• Auto-deploy. A write:repository token with All or Public only access, which can manage webhooks across every repository your account can reach. That is broader than deploybase needs

On instances older than 15.0 every token is account-wide and there is no selector. On 16.0 and later, connect without a token instead and the choice goes away.

GitLab tokens

Create the token where GitLab keeps that type:

• Project access token, limited to one project: in the project, Settings > Access tokens. Give it a role and the read_repository scope, or api and Maintainer for auto-deploy
• Personal access token, legacy or fine-grained, which reaches every project your account can: select your avatar, then Edit profile > Access > Personal access tokens, and pick the type from Generate token
• Deploy token, read-only: in the project, Settings > Repository, then expand Deploy tokens. Give it the read_repository scope

A deploy token needs its username

GitLab accepts a deploy token only together with its own username, which it shows when you create the token. By default that is gitlab+deploy-token- followed by a number, such as gitlab+deploy-token-123, unless you chose your own. Enter it in Deploy token username, which appears once you paste a token starting with gldt-, or send it as git_username through the API. Without it, deploybase refuses the token with git_error_code deploy_token_username_required before contacting GitLab.

Every other GitLab token works without a username, so leave git_username out for those.

A deploy token cannot deploy on push

Auto-deploy registers a webhook through GitLab’s API, and that API does not accept deploy tokens. Switching auto-deploy on with one is refused with a 422 naming auto_deploy_enabled. Deploy from the dashboard, the CLI or the API instead, or use a project access token with api and the Maintainer role.

Self-hosted GitLab

Paste your instance’s clone URL, for example https://git.example.com/you/repo.git. The instance must be reachable from the internet over HTTPS.

The dashboard recognises GitLab from the sign-in challenge your instance answers with, or from a token starting with glpat- or gldt-, including tokens your instance gives its own prefix, such as acme-glpat-. Builds, deploy tokens and auto-deploy then work as they do on gitlab.com. Through the API, send "git_provider": "gitlab".

Check it before you save

curl -X POST https://api.deploybase.eu/api/v1/projects/validate-git \
  -H "Authorization: Bearer $DEPLOYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "git_repo_url": "https://gitlab.com/you/repo.git",
    "git_provider": "gitlab",
    "git_token": "'"$GIT_TOKEN"'"
  }'

For a GitLab deploy token, add its username:

curl -X POST https://api.deploybase.eu/api/v1/projects/validate-git \
  -H "Authorization: Bearer $DEPLOYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "git_repo_url": "https://gitlab.com/you/repo.git",
    "git_provider": "gitlab",
    "git_token": "'"$GIT_TOKEN"'",
    "git_username": "gitlab+deploy-token-123"
  }'

Success is 200 with {"data": {"valid": true}}. A failure is 422, carrying a git_error_code in details that distinguishes the causes: auth_failed, repo_not_found, host_not_found, timeout, connection_failed, deploy_token_username_required or unknown.

With auth_failed, details.git_error_reason says which way the host refused:

• token_not_accepted: the host did not accept the token. It is mistyped, expired or revoked, or a deploy token went with the wrong username
• token_cannot_read: the host accepted the token, but it may not read the code. On GitLab, check the read_repository scope, or Code: Download on a fine-grained token
• token_needs_fine_grained: your GitLab group accepts only fine-grained tokens. Make one with Code: Download on the project

Worth running before you create the project, since it is the difference between a clear error now and a failed build later.

Set it on a project

curl -X PATCH "https://api.deploybase.eu/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $DEPLOYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "git_repo_url": "https://gitlab.com/you/repo.git",
    "git_provider": "gitlab",
    "git_token": "'"$GIT_TOKEN"'",
    "default_branch": "main"
  }'

A GitLab deploy token needs "git_username" here too. Sending a new git_token without git_username clears the stored username, and "git_username": "" clears it on its own.

git_provider accepts github, gitlab, bitbucket and codeberg. A self-hosted GitLab uses gitlab; leave it out and a token starting with glpat- or gldt- sets it for you. There is no separate value for a self-hosted Forgejo or Gitea instance: send codeberg, which selects the Forgejo-compatible behaviour whatever the hostname. default_branch is the branch that deploys to production; everything else builds a preview.

Rotating a token

Replace it with a PATCH and the next build uses the new one. Builds already running keep the credential they started with.

If a token expires, builds fail at the clone step with an authentication error rather than silently serving stale content. Provider tokens with an expiry date are worth a calendar entry, because nothing here will remind you.