Skip to main content

​
Overview

On your first sign in to the Qovery Console, you need to login via your Git provider account (GitHub, GitLab, or Bitbucket). This allows Qovery to manage your repositories and create webhooks to track push events and pull requests for auto-deployment and preview environments. Qovery offers two approaches for Git repository access:
  1. User-based access (default): Uses your personal Git provider login
  2. Git tokens (recommended): Centralized token management for decoupled permission control
This page focuses on the Git tokens approach, which provides organizations with better control and security.
Legacy GitHub App: The Qovery GitHub App is being deprecated and will be replaced by the Git tokens system. Existing users should migrate to tokens for better flexibility and control.

​
Git Tokens

Git tokens enable centralized management of Git repository access. Tokens are created within your Git provider and added to your Qovery organization, decoupling permissions from individual user accounts.

​
Managing Tokens on Git Provider

Create tokens in your Git provider with the appropriate permissions:

​
GitHub

GitHub supports two token types:
  • Personal Access Tokens (Classic)
  • Fine-Grained Personal Access Tokens
Classic tokens provide full control with simpler configuration.Required Permissions:
  • repo (Full control of private repositories) - Required
  • admin:repo_hook (Full control of repository hooks) - Required
  • read:org (Read org and team membership) - if using GitHub organizations
Steps:
  1. Go to GitHub Token Settings
  2. Click Generate new token (classic)
  3. Add a descriptive note (e.g., “Qovery Access”)
  4. Select the required scopes above
  5. Choose an expiration period
  6. Click Generate token and copy immediately
GitHub shows your token only once. Copy it immediately after generation.
GitHub vs GitHub Enterprise
When adding a GitHub token in Qovery:
  • GitHub (Cloud)
  • GitHub Enterprise
Use this option for repositories hosted on github.com:
  • No additional configuration needed
  • Uses standard GitHub.com API
  • Default option for most users

​
GitLab

GitLab supports project, group, and personal access tokens.
  • Project Tokens
  • Group Tokens
For access to specific projects:Required Configuration:
  • Role: Maintainer or Owner
  • Scopes:
    • api (Access the API) - Required
    • read_repository (Read access to repositories) - Required
Steps:
  1. Go to your GitLab project > Settings > Access Tokens
  2. Click Add new token
  3. Enter token name and expiration date
  4. Select Maintainer or Owner role
  5. Check required scopes
  6. Click Create project access token and copy immediately
GitLab.com vs Self-hosted
When adding a GitLab token in Qovery:
  • GitLab.com: No additional configuration needed
  • Self-hosted GitLab: Provide your GitLab server URL (e.g., https://gitlab.company.com)
Ensure your self-hosted GitLab instance is accessible from Qovery.

​
Bitbucket

Bitbucket supports repository and workspace access tokens.
  • Repository Access Tokens
  • Workspace Access Tokens
For access to specific repositories:Required Permissions:
  • Repositories: Read - Required
  • Pull requests: Read and write - Required
  • Webhooks: Read and write - Required
Steps:
  1. Go to repository > Repository settings > Access tokens
  2. Click Create Repository Access Token
  3. Enter token name and expiration
  4. Select required permissions
  5. Click Create and copy immediately

​
Token Expiration

Git provider tokens typically include expiration dates. To maintain continuous repository access:
  1. Monitor expiration: Check your Git provider settings regularly
  2. Renew before expiry: Either extend expiration (if supported) or generate a new token
  3. Update in Qovery: Replace the old token value in Qovery organization settings
  4. Verify connection: Test with a deployment
  5. Revoke old token: Delete the old token from your Git provider
Always update tokens in Qovery BEFORE they expire to avoid deployment interruptions.

​
Managing Tokens on Qovery

Once you’ve created a token in your Git provider, manage it in Qovery:

​
Create the Token

1

Access Organization Settings

Click the “Wheel” button (⚙️) on the left navigation barHow to access your organization settings
2

Navigate to Git Repository Access

Open the Git Repository Access section within organization settings
3

Add Token

Click Add Token button
4

Configure Token

Provide:
  • Git Provider: Select GitHub, GitLab, or Bitbucket
  • Name: Descriptive name (e.g., “GitHub Main Org”)
  • Token: Paste your Git provider access token
  • URL (for self-hosted only): Your Git server URL
  • Workspace (for Bitbucket only): Your Bitbucket workspace name
5

Test and Save

Qovery will validate the token and verify access. Click Save to complete.
Only users with Owner, Admin, or DevOps roles can manage Git tokens.

​
Using the Token

Once configured, Git tokens are automatically used when:
  • Creating new applications or services from Git repositories
  • Cloning repository code during builds
  • Monitoring repository changes for auto-deployment
  • Accessing Dockerfile and build context
  • Configuring webhooks for auto-deploy and preview environments
When creating a service:
  1. Choose Git Repository as the source
  2. Select Organization Token (instead of personal Git account)
  3. Choose the Git provider type
  4. Select repository and branch

​
Update the Token

1

Locate Token

Find the token in the Git Repository Access list
2

Click Edit

Click the Edit button next to the token
3

Modify Details

Update token value, name, or URL as needed
4

Save Changes

Click Save to apply changes
Updating a token affects all applications using repositories from this Git provider connection.

​
Delete the Token

To remove a Git token:
  1. Locate the token in the Git Repository Access list
  2. Click the Delete button (trash icon)
  3. Confirm deletion
Applications currently using repositories accessed through this token may fail to build or deploy. Configure alternative access before deletion.

​
Deprecated: Qovery GitHub App

The Qovery GitHub App is being deprecated and will be replaced by Git tokens. Existing users should migrate to the token-based approach described above.
The legacy Qovery GitHub App provided GitHub repository access through an OAuth app. While still functional for existing users, new users should use Git tokens instead.

​
Migration Recommendation

  1. Create GitHub personal access token (see instructions above)
  2. Add token to Qovery organization settings
  3. Update applications to use organization token instead of GitHub App
  4. Uninstall Qovery GitHub App once migration is complete

​
Best Practices

Use organizational Git tokens instead of personal accounts for better security and to decouple deployments from individual user access.
Always set an expiration date (90 days to 1 year) and set reminders for token rotation.
Create dedicated Git accounts for Qovery integration that aren’t tied to individual developers.
Use clear names like github-main-org-production or gitlab-team-alpha to identify tokens easily.
Rotate tokens periodically for security:
  1. Create new token with same permissions
  2. Update in Qovery
  3. Test with deployment
  4. Revoke old token

Applications

Deploy applications from Git repositories

Container Registry

Manage container registries

Auto-Deploy

Configure automatic deployments

CI/CD Integration

Integrate with your CI/CD pipeline