Git Provider Token Setup

dbdeux connects to your Git provider to clone repositories, commit changes, manage branches, post PR comments, and set commit statuses for Slimmer CI. Each provider requires a token with specific permissions.

This guide walks you through creating a token for each supported provider with the correct scopes.

GitHub

Token Type

Use a Fine-grained personal access token (recommended) or a Classic personal access token.

Required Scopes (Classic Token)

Scope	Why it's needed
repo (full control)	Clone private repos, create branches, push commits, read/write file content, manage commit statuses, and interact with pull requests

The repo scope is a top-level scope that includes sub-permissions for repository contents, commit statuses, deployments, and pull requests.

Fine-Grained Token Permissions (Recommended)

Fine-grained tokens allow more targeted access:

Permission	Access level	Why it's needed
Contents	Read and write	Clone repo, read files, push commits, create/update files
Pull requests	Read and write	Post AI review comments, PR digest comments
Commit statuses	Read and write	Post Slimmer CI pass/fail status on PRs
Webhooks	Read and write	Auto-provision PR/push webhooks for Slimmer CI
Metadata	Read-only	Required by GitHub for all fine-grained tokens

How to Create

1. Go to github.com/settings/tokens
2. Click Generate new token > Fine-grained token (recommended)
3. Set a descriptive name (e.g., "dbdeux")
4. Choose an expiration (or set to no expiration for uninterrupted access)
5. Under Repository access, select the repositories you want to connect (or "All repositories")
6. Under Permissions, enable the permissions listed above
7. Click Generate token
8. Copy the token immediately (you won't see it again)

GitHub Enterprise Server

The same scopes apply. When connecting in dbdeux, provide your custom server URL (e.g., https://github.yourcompany.com) during setup.

---

GitLab

Token Type

Use a Personal Access Token (or Project/Group Access Token for scoped access).

Required Scopes

Scope	Why it's needed
api	Full API access for webhooks, commit statuses, merge request comments, and project metadata
read_repository	Clone and read repository contents via Git
write_repository	Push commits, create branches, update files via Git

How to Create

1. Go to User Settings > Access Tokens (or Project > Settings > Access Tokens for project-scoped tokens)
2. Enter a name (e.g., "dbdeux")
3. Set an expiration date (or leave blank for no expiration, if allowed by your admin)
4. Check the scopes: api, read_repository, write_repository
5. Click Create personal access token
6. Copy the token immediately

Self-Managed GitLab

The same scopes apply. Provide your instance URL (e.g., https://gitlab.yourcompany.com) during setup.

---

Azure DevOps

Token Type

Use a Personal Access Token (PAT).

Required Scopes

Scope	Why it's needed
Code (Read & Write)	Clone repos, create branches, push commits, read file content
Code (Status)	Post Slimmer CI commit statuses on pull requests
Pull Request Threads (Read & Write)	Post AI review and PR digest comments
Service Hooks (Read & Query)	Auto-provision webhooks for push/PR events

In the Azure DevOps token UI, these correspond to:

• vso.code_write - Code: Read & Write
• vso.code_status - Code: Status
• vso.threads_write - Pull Request Threads: Read & Write
• vso.hooks - Service Hooks: Read & Query

How to Create

1. Go to User Settings > Personal access tokens (click your avatar in the top-right corner)
2. Click + New Token
3. Enter a name (e.g., "dbdeux")
4. Select your organization
5. Set expiration (maximum 1 year; set a calendar reminder to rotate)
6. Under Scopes, select Custom defined then enable:
   • Code: Read & Write
   • Code: Status
   • Pull Request Threads: Read & Write
   • Service Hooks: Read & Query
7. Click Create
8. Copy the token immediately

Azure DevOps Server (Self-Hosted)

The same scopes apply. Provide your server URL (e.g., https://devops.yourcompany.com/DefaultCollection) during setup.

---

Bitbucket Cloud

Token Type

Use an App Password (recommended) or a Repository/Workspace Access Token.

Required Permissions (App Password)

Permission	Why it's needed
Repositories: Read	Clone and read repository contents
Repositories: Write	Push commits, create branches, update files
Pull requests: Read	Read PR metadata for Slimmer CI
Pull requests: Write	Post AI review and PR digest comments
Webhooks: Read and write	Auto-provision PR/push webhooks for Slimmer CI

How to Create (App Password)

1. Go to Personal settings > App passwords (click your avatar > Personal settings)
2. Click Create app password
3. Enter a label (e.g., "dbdeux")
4. Check the permissions listed above
5. Click Create
6. Copy the password immediately (you won't see it again)

When connecting in dbdeux, enter your Bitbucket username and the app password as the token.

Workspace Access Token (Alternative)

If your admin prefers workspace-scoped tokens:

1. Go to Workspace settings > Access tokens
2. Create a token with the same permissions as above
3. Workspace tokens do not require a username (use the token directly)

---

Summary Table

Provider	Token type	Key scopes
GitHub	Fine-grained PAT	Contents (RW), Pull requests (RW), Commit statuses (RW), Webhooks (RW)
GitLab	Personal Access Token	api, read_repository, write_repository
Azure DevOps	Personal Access Token	Code (RW), Code Status, PR Threads (RW), Service Hooks
Bitbucket	App Password	Repositories (RW), Pull requests (RW), Webhooks (RW)

Best Practices

• Use the minimum required scopes listed above. Do not grant full account access unless necessary.
• Use service accounts for team/production setups rather than personal accounts. This prevents access loss if a team member leaves.
• Set reminders to rotate tokens before they expire, especially for Azure DevOps (max 1-year expiry).
• Name tokens descriptively (e.g., "dbdeux-production") so you can identify and revoke them later.
• One token per environment if you use separate dev/staging/production connections.

Connecting in dbdeux

Once you have your token:

1. Go to Settings > Version Control
2. Click + Connect Provider
3. Select your provider (GitHub, GitLab, Azure DevOps, or Bitbucket)
4. Paste your token
5. For self-hosted instances, enter your custom URL
6. Click Test Connection to verify permissions
7. Select the repositories to connect

If the connection test fails, double-check that all required scopes are enabled on your token.