SCM Token Permissions Matrix

The definitive reference for token permissions. Get PR Decoration and Commit Scanning working on the first try.

IMPORTANT

Role Alert: Users with "Guest" or "Reporter" roles on GitLab will fail webhook creation. Minimum required role is Developer.

---

GitHub

Classic Personal Access Tokens

Feature	Required Scope	Why?
Repo Linking	repo	Read and clone repositories
Webhooks	admin:repo_hook	Create/manage webhooks for PR triggers
PR Comments	write:discussion	Post scan results as PR comments

Setup Steps

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token (classic)
3. Required scopes:
   • ✅ repo (Full control of private repositories)
   • ✅ admin:repo_hook (Full control of repository hooks)
   • ✅ write:discussion (Read and write team discussions)

Fine-Grained Personal Access Tokens ⭐

Feature	Required Permission	Level	Why?
Repo Access	Contents	Read	Access code and files
PR Management	Pull requests	Read & Write	Create PR comments and decorations
Webhooks	Webhooks	Read & Write	Automatically create scan triggers
Status Checks	Commit statuses	Read & Write	Update quality gate status on PRs

Setup Steps

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Generate new token
3. Repository access: Selected repositories (choose your target repos)
4. Required permissions:
   • ✅ Contents: Read
   • ✅ Pull requests: Read and write
   • ✅ Webhooks: Read and write
   • ✅ Commit statuses: Read and write

---

GitLab

Feature	Required Scope	Why?
Repo Linking	read_repository	Clone and read repository contents
API Access	api	Full API access for webhooks and comments
Repo Management	write_repository	Update repository settings (webhooks)

Setup Steps

1. GitLab → User Settings → Access Tokens
2. Create personal access token
3. Required scopes:
   • ✅ api (Complete read/write access to the API)
   • ✅ read_repository (Read access to repositories)
   • ✅ write_repository (Write access to repositories)

WARNING

Role Requirement: Your GitLab account must have Developer role or higher on target repositories. "Guest" and "Reporter" roles lack webhook creation permissions.

---

Bitbucket Cloud

Feature	Required Permission	Why?
Webhooks	webhook	Create repository webhooks for automation
Repository Access	repository:write	Read repository data and manage settings
PR Management	pullrequest	Comment on and update pull requests

Setup Steps

1. Bitbucket → Personal Settings → App passwords
2. Create app password
3. Required permissions:
   • ✅ webhook (Manage repository webhooks)
   • ✅ repository:write (Write access to repositories)
   • ✅ pullrequest (Read and write access to pull requests)

---

Azure DevOps

Feature	Required Scope	Why?
Code Access	Code (Read & Write)	Access repositories and manage webhooks
Project Info	Project & Team (Read)	Read project metadata and team information

Setup Steps

1. Azure DevOps → User Settings → Personal access tokens
2. New Token
3. Required scopes:
   • ✅ Code → Read & write
   • ✅ Project and Team → Read

WARNING

Azure DevOps Limitation: Commit-level status updates are not supported. Only Pull Request status checks are available.

---

Manual Webhook Configuration

If your token lacks webhook permissions, configure webhooks manually:

Webhook Payload URL

{{base_url}}/api/views/repositories/pullrequests/webhooks

Replace with your BrowserStack Code Quality server URL:

• Example: https://your-server.com/api/views/repositories/pullrequests/webhooks

Required Events

SCM Provider	Events to Enable
GitHub	Pull requests, Push
GitLab	Merge request events, Push events
Bitbucket	Pull request created/updated, Repository push
Azure DevOps	Pull request created/updated, Git push

---

Common Webhook Errors

Error Code	Cause	Solution
401 Unauthorized	Invalid or expired token	Regenerate token with correct scopes
403 Forbidden	Insufficient permissions	Verify role (Developer+) and token scopes
422 Unprocessable Entity	Invalid repository URL or network issue	Check repository accessibility and network connectivity
404 Not Found	Repository not accessible	Confirm repository exists and token has read access

---

Best Practices

Security

• Minimal Scopes: Grant only required permissions
• Token Rotation: Regenerate annually or when team members leave
• Environment Variables: Never hardcode tokens in repositories
• Network Security: Use HTTPS-only connections

️ Limitations

• File Limit: Scans limited to 100 files per PR/commit
• Commit Limit: Maximum 300 commits per webhook payload
• Network Access: BrowserStack Code Quality must reach your SCM provider

Troubleshooting

1. Connection Test: Use VCA connection test to verify permissions
2. Webhook Logs: Check SCM provider's webhook delivery logs
3. Role Verification: Confirm Developer+ roles on GitLab/Bitbucket
4. Token Expiry: Check token expiration dates regularly

---

Next Steps

After configuring tokens:

1. Set up Version Control Account – Connect your SCM with proper tokens
2. Enable SCM Workflows – Activate automatic commit and PR analysis
3. Configure Quality Gates – Set merge approval standards

TIP

Pro Tip: Test with a single repository first. Once PR decoration works correctly, scale to your full repository portfolio.