SCM permissions

This page describes the minimum permissions required for source code management (SCM) integrations to allow CloudBees platform to commit workflow YAML files and create webhooks in your connected repositories.

When you create, edit, or delete a workflow in the UI, CloudBees platform commits a workflow YAML file to your connected source repository. The commit uses the credentials (token or app installation) configured for your application.

To succeed, the token or user must have the minimum repository permissions listed below. If the default branch is protected, you might need to submit a pull request instead of committing directly.

For setup steps and supported SCM integrations, refer to SCM integrations.

Minimum permissions by SCM

When a workflow is created, edited, or deleted in the UI, CloudBees platform commits those changes to your connected repository. The following table shows the minimum permissions required for each SCM to complete those commits successfully.

SCM Commit to the repository If the branch is protected Notes

SCM	Commit to the repository	If the branch is protected	Notes
GitHub (Cloud or Enterprise)	Token with repository Contents: `Read and write` (fine-grained personal access token) or classic `repo` scope, and the user has write access.	Direct pushes may be blocked by branch protection. Create a branch and open a pull request.	Fine-grained PAT scopes: Contents: `Read and write` (+ Metadata: `Read`). Classic: `repo` (least-privileged acceptable). No manual token configuration is required when using the CloudBees GitHub App—the installation handles authentication and permissions automatically.
GitLab (SaaS or self-managed)	Developers can push to non-protected branches; Maintainer (or higher) is typically required where protections apply.	Protected branch rules decide who can push or merge. Create a branch and open a merge request if direct push is blocked.	Requires a personal access token with the `api` scope. Project-level tokens are not supported. Project roles and branch protection rules govern effective rights.
Bitbucket Cloud	Write permission on the repository (and allowed by branch restrictions).	If branch restrictions block pushes, create a branch and open a pull request.	Repository admin is not required for content pushes, only write (unless restrictions specify otherwise).
Bitbucket Server or Data Center	Write permission at both the project and repository levels, and allowed by any branch permissions.	If branch permissions restrict direct pushes, create a branch and open a pull request.	Project or repository admins configure branch and merge checks.
Gerrit	Push to `refs/for/<branch>` to create a change for review, or push to `refs/heads/<branch>` to push directly (if policy allows).	If direct pushes to `refs/heads/<branch>` are denied, push to `refs/for/<branch>` and have a reviewer submit it.	Access is set in Projects Access. Creating new branches or tags requires Create reference; edits to existing branches only need Push.

GitHub (Cloud or Enterprise)

Token with repository Contents: Read and write (fine-grained personal access token) or classic repo scope, and the user has write access.

Direct pushes may be blocked by branch protection. Create a branch and open a pull request.

Fine-grained PAT scopes: Contents: Read and write (+ Metadata: Read). Classic: repo (least-privileged acceptable).
No manual token configuration is required when using the CloudBees GitHub App—the installation handles authentication and permissions automatically.

GitLab (SaaS or self-managed)

Developers can push to non-protected branches; Maintainer (or higher) is typically required where protections apply.

Protected branch rules decide who can push or merge. Create a branch and open a merge request if direct push is blocked.

Requires a personal access token with the api scope. Project-level tokens are not supported. Project roles and branch protection rules govern effective rights.

Bitbucket Cloud

Write permission on the repository (and allowed by branch restrictions).

If branch restrictions block pushes, create a branch and open a pull request.

Repository admin is not required for content pushes, only write (unless restrictions specify otherwise).

Bitbucket Server or Data Center

Write permission at both the project and repository levels, and allowed by any branch permissions.

If branch permissions restrict direct pushes, create a branch and open a pull request.

Project or repository admins configure branch and merge checks.

Gerrit

Push to refs/for/<branch> to create a change for review, or push to refs/heads/<branch> to push directly (if policy allows).

If direct pushes to refs/heads/<branch> are denied, push to refs/for/<branch> and have a reviewer submit it.

Access is set in Projects Access. Creating new branches or tags requires Create reference; edits to existing branches only need Push.

Permissions to create webhooks

Webhooks allow CloudBees platform to listen for events such as commits, merges, and pull requests in your source repositories. The following table lists the minimum permissions required to create and manage webhooks for each supported SCM.

SCM Who can create webhooks How to configure

SCM	Who can create webhooks	How to configure
GitHub	Repository admin or owner. For tokens, a fine-grained PAT must include Webhooks: `Read and write` on the repository.	From Settings Webhooks in the GitHub UI, or use the REST API with a token that includes Webhooks: `Read and write` and Metadata: `Read`.
GitLab	Maintainer (project) or owner (group).	Settings Webhooks (per project or group) or REST API.
Bitbucket Cloud	Repository admin.	Repository Settings Webhooks or REST API.
Bitbucket Server or Data Center	Project admin (project level) or repository admin (repository level).	Project or repository Settings Webhooks or REST API.
Gerrit	Project owner (owner on `refs/*`) or account allowed to update `refs/meta/config`. Admin must first enable the webhooks plugin.	Configure through the webhooks plugin (REST) or by updating `webhooks.config` in `refs/meta/config` for the project.

GitHub

Repository admin or owner. For tokens, a fine-grained PAT must include Webhooks: Read and write on the repository.

From Settings Webhooks in the GitHub UI, or use the REST API with a token that includes Webhooks: Read and write and Metadata: Read.

GitLab

Maintainer (project) or owner (group).

Settings Webhooks (per project or group) or REST API.

Bitbucket Cloud

Repository admin.

Repository Settings Webhooks or REST API.

Bitbucket Server or Data Center

Project admin (project level) or repository admin (repository level).

Project or repository Settings Webhooks or REST API.

Gerrit

Project owner (owner on refs/*) or account allowed to update refs/meta/config. Admin must first enable the webhooks plugin.

Configure through the webhooks plugin (REST) or by updating webhooks.config in refs/meta/config for the project.

Troubleshooting

If a commit fails due to insufficient permissions, review the error message and refer to the guidance below for your SCM.

General

Commit failed: insufficient permissions: The token or user lacks write permission on the target branch, or branch policy requires a pull request or merge request. Use a feature branch and open a pull request or merge request.
Reference update rejected: Branch protection, required checks, or merge gates are blocking direct pushes.

GitHub

Error mentions branch protection or required status checks: Push to a branch and open a pull request. Confirm that the token has repository Contents: Read and write (fine-grained) or repo (classic).

GitLab

You are not allowed to push code to this project: The user is a developer on a protected branch. Elevate to Maintainer or use a branch and merge request per policy.

Bitbucket Cloud or Server

Push rejected by branch restrictions: Repository write permission is not enough; the branch has restrictions. Use a pull request or adjust the branch restriction to allow the integration user.

Gerrit

Push not permitted to refs/heads/<branch>: Direct pushes are denied. Push to refs/for/<branch> instead.
Cannot create change when pushing to refs/for/<branch>: Grant push permission on refs/for/refs/heads/* to the integration account.
Webhooks: If REST calls fail with permission errors, ensure that the webhooks plugin is enabled and the caller can update refs/meta/config (Project Owner or Admin).

Example GitHub token setups

Fine-grained PAT (preferred, least privilege for a single repository)

Repository access: The target repository.

Permissions:

Repository permissions → Contents: Read and write
Repository permissions → Metadata: Read
(Optional, for managing webhooks) Webhooks: Read and write

Classic PAT (broader)

Scopes: repo (for content).

Add admin:repo_hook only if the token will also manage webhooks.

The SCM integration token must match the application’s connected source provider. If a commit fails, verify that the user or token has write access and the required webhook permissions.