Deployment User in Git - Permission checklist

The Git operations are carried out by the Git identity you connect to Gearset. For a team-shared pipeline this is usually a dedicated service user (sometimes called an integration or deployment user)

Note: Gearset respects the access rules, branch protections and settings you have configured in your Git provider, and never overrides them. Gearset also cannot grant repository access from inside the app — you set all of the permissions below in your provider.

GitHub

Connect as a dedicated service user — still required even when you use the GitHub App.

Permission / setting	What to do
Repository read/write	Required. The service user must be able to clone the repository and push branches.
Repository Admin	Required for webhooks. GitHub only allows webhooks to be created at Admin level. The GitHub App controls which repos are visible but doesn't grant this role — set Admin on the repository itself.
Open / merge PRs and manage branches	Required. Lets Gearset raise, merge and tidy up the promotion pull requests it creates.
Signed-commit GPG key	Only if signed commits are enforced. Upload the service user's Gearset GPG public key to GitHub so its commits show as verified.
GitHub App installation	One-time, if connecting via the App. Installed by a GitHub organisation owner/admin. The app improves security (it limits which repositories are reachable and uses short-lived tokens), but it does not replace the service user — you still connect as a dedicated service user. The app only changes how the token is obtained and which repositories it can see

Note: On a brand-new repository, GitHub does not always grant the existing service user read/write automatically. If pipeline setup is blocked on a new repo, add read/write for the service user manually.

GitLab

Connect as a service user, or with a Personal / Project / Group access token.

Permission / setting	What to do
Project access (read/write)	Required. A `403 Forbidden` error means the identity has no access — ask a project admin to add it.
Maintainer role	Required — Developer is not enough. By default GitLab only lets Maintainers push to protected branches, so a Developer-level user fails during setup. (Or adjust the protected-branch "allowed to push and merge" setting.)
Create webhooks	Required. Gearset adds these automatically, as long as the role is high enough or the token includes webhook scope.
Open / merge MRs and manage branches	Required. Lets Gearset raise and merge the promotion merge requests it creates.
Access-token scopes	If connecting with a token. Tick the scopes covering repository read/write and webhooks (the `api` scope) when you create it. Project/Group tokens create a non-seat bot user behind the scenes.
"Reject unsigned commits" setting	Only if enabled. It can stop Gearset creating the repo's first files — set up commit signing or turn it off for this flow.

Azure DevOps

Connect as a dedicated service user.

Permission / setting	What to do
Repository read/write ("Contribute")	Required. Give the service user the Contribute permission so it can read and push.
Force Push	Required — the one most teams miss. Azure DevOps only allows a branch to be deleted with Force Push, and Gearset deletes the temporary `gs-…` branches it creates. Without it you'll see `TF401027` / "Force push permission is required", and promotion, sync or cleanup fails.
Create service hooks	Required. Gearset uses these for pipeline and CI job webhooks.
Open / merge PRs and manage branches	Required. Lets Gearset raise, merge and clean up promotion pull requests.
Signed-commit GPG key	Only if enforced. Upload the service user's Gearset GPG public key.

Note: Grant Force Push to the service user only, then deny it on main and your environment branches (Project Settings → Repositories → Security). This lets Gearset clean up its own temporary branches while ensuring the service user can never overwrite a protected branch.

Bitbucket

Connect as a dedicated service account — not a personal user.

Permission / setting	What to do
Repository Admin	Required. Bitbucket only allows webhooks at Repository Admin (`repository:admin`) level, and Gearset needs webhooks. This role also includes repository read/write.
Update PRs and restore branches	Required. The service account needs write/admin for this — an "Access denied. You must have write or admin access" message means it's missing.
Two-step verification (2FA) — Cloud	Required on Bitbucket Cloud. Enable 2FA on the service account, or webhook creation fails.
SSH key / HTTPS credentials — Server	Required on Bitbucket Server. Register the service account's SSH key (or provide valid HTTPS credentials) and make sure Gearset can reach the host.
Bitbucket app installation	One-time. Installing the app needs Workspace Admin — have someone with that on the setup call. The app improves security (it limits which repositories are reachable and uses short-lived tokens), but it does not replace the service user — you still connect as a dedicated service user. The app only changes how the token is obtained and which repositories it can see.
Force push	Only if you hit sync failures. Not normally needed — a fallback for promotion branches that can't update by a normal merge.

Note: Bitbucket has two roles both called "admin". Repository Admin is the day-to-day permission the service account needs to run. Workspace Admin is only needed once, to install the app. They are not the same, and the service account does not need Workspace Admin day-to-day.

Troubleshooting: common errors and what they mean

Error or symptom	Likely cause and fix
Cannot access repository	The service user lacks read/write access, or the repo URL changed. This banner can also appear during a transient provider incident or an API rate limit — check status first.
You do not have permission to create a webhook	The user can't create webhooks. GitHub: make it a repository Admin. Bitbucket: grant Repository Admin, and on Cloud enable 2FA.
Push failed: Force push permission is required / TF401027	Grant Force Push to the service user (Azure DevOps branch deletion, or a conflicting promotion sync on any provider).
403 Forbidden / GitLab client could not fetch repository	The GitLab service user has no access to the project — grant it, and check the role is Maintainer.
Your credentials lack required privilege scopes (required: repository:admin)	The Bitbucket service account is not a Repository Admin.
Commits show as Unverified, or are rejected by commit checks	A signed-commit rule is enforced — add the service user's GPG public key to the provider.
Pipeline setup is blocked on a brand-new repository	The team-shared account wasn't auto-granted read/write on the new repo — add it manually.