Source code management (SCM) integrations in CloudBees Unify require specific permissions to commit workflow files and create webhooks in connected repositories. Use this reference when configuring SCM integrations, troubleshooting permission issues, or setting up authentication tokens.
Repository commit permissions
Repository commit permissions control CloudBees Unify’s ability to write workflow YAML files to connected repositories. Each SCM system has different permission models and token requirements.
| SCM system | Minimum permissions | Protected branch handling | Configuration notes |
|---|---|---|---|
GitHub (Cloud or Enterprise) |
Token with repository Contents: |
Direct pushes may be blocked by branch protection. Create a branch and open a pull request |
Fine-grained PAT scopes: Contents: |
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 |
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 |
If direct pushes to |
Access is set in . Creating new branches or tags requires Create reference; edits to existing branches only need Push |
Webhook creation permissions
Webhook permissions allow CloudBees Unify to create and manage event listeners for commits, merges, and pull requests in source repositories. Administrative permissions are typically required for webhook management.
| SCM system | Required roles/permissions | Configuration method |
|---|---|---|
GitHub |
Repository admin or owner. For tokens, a fine-grained PAT must include Webhooks: |
From in the GitHub UI, or use the REST API with a token that includes Webhooks: |
GitLab |
Maintainer (project) or owner (group) |
(per project or group) or REST API |
Bitbucket Cloud |
Repository admin |
Repository or REST API |
Bitbucket Server or Data Center |
Project admin (project level) or repository admin (repository level) |
Project or repository or REST API |
Gerrit |
Project owner (owner on |
Configure through the webhooks plugin (REST) or by updating |
Authentication token specifications
Authentication tokens provide programmatic access to SCM systems with defined permission scopes. Token requirements vary by SCM provider and intended functionality.
| Token type | Required scopes/permissions | Access level | Notes |
|---|---|---|---|
GitHub fine-grained PAT (preferred) |
Repository permissions → Contents: |
Target repository only |
Least privilege option. Repository access must be explicitly configured |
GitHub classic PAT |
|
All repositories accessible to user |
Broader access than fine-grained tokens. Legacy option |
GitLab personal access token |
|
Determined by user’s project role |
Project-level tokens not supported. Access controlled by project roles and branch protection |
Bitbucket access token |
Write permission on repositories |
Repository-level permissions |
Admin permissions required for webhook creation. Controlled by branch restrictions |
Gerrit access configuration |
Push on |
Project-level permissions |
Project owner or |
Troubleshooting
Permission errors occur when authentication tokens lack required access levels or branch policies block operations. Review the error message and refer to the guidance below for your SCM system.
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) orrepo(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).
| 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. |
Example Bitbucket token setups
The following examples show recommended token configurations for common Bitbucket use cases.
Repository access token
A repository access token is scoped to a single repository. Create one in Bitbucket under .
Required permissions:
-
Repositories: Read and write
-
Pull requests: Read and write
-
Webhooks: Read and write
To cover multiple repositories with a single token, use a Project or Workspace access token instead. For details on token types, scope support, and limitations, refer to Bitbucket access tokens reference.