This guide walks you through creating Personal Access Tokens (PATs) for GitHub, GitLab, and Bitbucket to use with Ampel. By the end, you'll be able to add provider accounts directly through the Ampel UI without needing OAuth configuration.

• Prerequisites
• Understanding PATs
• GitHub PAT Setup
• GitLab PAT Setup
• Bitbucket PAT Setup
• Adding Accounts to Ampel
• Security Best Practices
• Troubleshooting
• Additional Resources

Before you begin, make sure you have:

• Accounts on the platforms you want to integrate (GitHub, GitLab, and/or Bitbucket)
• Access to create PATs/app passwords (available on all account types)
• Ampel running and accessible (local or deployed)

Personal Access Tokens (PATs) are a secure way to authenticate with Git providers without sharing your password. They offer several advantages:

1. Log in to GitHub
2. Click your profile picture (top-right corner)
3. Select Settings
4. Scroll down and click Developer settings (left sidebar)
5. Click Personal access tokens
6. Choose Tokens (classic) or Fine-grained tokens (recommended)

1. Click Generate new token > Generate new token (fine-grained)
2. Fill in the token details:

3. Under Permissions, configure:

Repository permissions:

Account permissions:

If you prefer classic tokens:

1. Click Generate new token > Generate new token (classic)
2. Fill in the details:

3. Select scopes:

1. Click Generate token
2. Copy the token immediately - you won't see it again!
3. Store it securely (you'll paste it into Ampel in the next section)

Quick URL: https://github.com/settings/tokens/new

1. Log in to GitLab (or your self-hosted instance)
2. Click your avatar (top-right)
3. Select Edit profile
4. Click Access Tokens (left sidebar)
5. Scroll to Add new token

Quick URL: https://gitlab.com/-/profile/personal_access_tokens

Fill in the token details:

Check the following scopes:

For read-only access: Use read_api and read_repository instead of api.

For write access (merge, comment): Include api scope.

1. Click Create personal access token
2. Copy the token immediately - GitLab shows it only once!
3. Store it securely

For self-hosted GitLab instances, the process is identical. You'll also need to configure the base URL in Ampel when adding the account.

Bitbucket uses "App Passwords" instead of PATs. They work similarly but are created differently.

1. Log in to Bitbucket
2. Click your avatar (bottom-left)
3. Select Personal settings
4. Click App passwords (left sidebar, under "Access management")
5. Click Create app password

Quick URL: https://bitbucket.org/account/settings/app-passwords/new

Check the following permissions:

Account:

Workspace membership:

Repositories:

Pull requests:

1. Click Create
2. Copy the app password immediately - you won't see it again!
3. Store it securely

Note: You'll use your Bitbucket username along with the app password when adding the account to Ampel.

Once you have your tokens/app passwords, add them to Ampel:

1. Log in to Ampel
2. Navigate to Settings > Provider Accounts
3. Click Add Account
4. Select the provider (GitHub, GitLab, or Bitbucket)
5. Fill in the form:

GitHub:

GitLab:

Bitbucket:

6. Click Test Connection to verify
7. Click Save

You can add multiple accounts from the same provider:

• Personal GitHub + Work GitHub
• GitLab.com + Self-hosted GitLab
• Multiple Bitbucket workspaces

Each account is stored securely with encrypted tokens.

1. Use expiration dates

   • Set tokens to expire in 90 days or less
   • Rotate tokens periodically
   • Remove unused tokens

2. Grant minimum permissions

   • Only enable the scopes you actually need
   • Use read-only access when write isn't required
   • Review permissions quarterly

3. One token per application

   • Create separate tokens for different tools
   • Easier to identify and revoke if compromised
   • Better audit trail

4. Never commit tokens to version control

   • Tokens are stored encrypted in Ampel's database
   • Don't share tokens via email or chat
   • Use secure password managers for temporary storage

Ampel stores tokens securely:

• Encryption: AES-256-GCM encryption at rest
• Encryption key: Stored separately in environment variables
• Database: Encrypted tokens stored in PostgreSQL
• Memory: Tokens only decrypted when actively used

If a token is exposed:

1. Revoke immediately:

   • GitHub: Settings > Developer settings > Personal access tokens > Delete
   • GitLab: Profile > Access Tokens > Revoke
   • Bitbucket: Personal settings > App passwords > Delete

2. Create a new token following the steps above

3. Update Ampel with the new token via Settings > Provider Accounts

4. Review access logs on the provider platform for suspicious activity

GitHub:

• View token usage at https://github.com/settings/tokens
• Shows last used date and IP address

GitLab:

• View active tokens at https://gitlab.com/-/profile/personal_access_tokens
• Shows last used date and expiration

Bitbucket:

• View app passwords at https://bitbucket.org/account/settings/app-passwords/
• Shows creation date (no usage tracking)

"Invalid token" error

• Verify you copied the entire token (no truncation)
• Check for extra whitespace when pasting
• Ensure the token hasn't expired
• Confirm the token has the required scopes

"Insufficient permissions" error

• Review the token scopes/permissions
• For GitHub: Ensure repo scope is enabled
• For GitLab: Ensure api or read_api scope is enabled
• For Bitbucket: Ensure repositories and pull requests have read permission

"Token expired" error

• Create a new token (tokens can't be renewed)
• Update the account in Ampel settings
• Consider using a longer expiration next time

Can't see repositories after connecting

• GitHub (fine-grained): Ensure you selected repository access
• GitHub (classic): Token may only have access to public repos
• GitLab: Check project visibility and token scopes
• Bitbucket: Verify workspace membership and repository permissions

You can test tokens manually using curl:

GitHub:

curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

GitLab:

curl -H "Authorization: Bearer YOUR_TOKEN" https://gitlab.com/api/v4/user

Bitbucket:

curl -u YOUR_USERNAME:YOUR_APP_PASSWORD https://api.bitbucket.org/2.0/user

If these commands fail, the token itself is invalid.

GitHub:

• Creating a personal access token
• Fine-grained personal access tokens
• Token scopes

GitLab:

• Personal access tokens
• Token scopes

Bitbucket:

• App passwords
• Repository access tokens

• OWASP Token Best Practices
• Git Provider Security Guides

If you previously used OAuth configuration:

1. Create PATs for each provider following the guides above
2. Add accounts via Ampel UI (Settings > Provider Accounts)
3. Existing OAuth environment variables are no longer needed
4. The .env file no longer requires OAuth credentials
5. All authentication is now handled through provider accounts in the database

This PAT-based approach is simpler, more flexible, and doesn't require OAuth application registration.