Git SCM Integration

Flipt v2 supports Source Control Management (SCM) for Git repositories.

This functionality is only available in Flipt v2 Pro. Learn more about our commercial license or purchase a monthly or annual license.

Prerequisites

Flipt v2
A Flipt v2 environment configured with Git Sync
A Flipt v2 Pro license or trial license

Flipt v2 SCM integration supports most of the major Git providers including GitHub, GitLab, Bitbucket, Gitea, and Azure DevOps.

1. Configure SCM Integration

This section will walk you through configuring Flipt v2 to more deeply integrate with your Git provider to enable features like Merge Proposals.

GitHub
Bitbucket
Azure DevOps
GitLab

GitHub Integration

1. Create a Personal Access Token (PAT)

Go to GitHub Settings > Developer settings > Personal access tokens.
Click “Generate new token”
Give your token a name
Select a resource owner (e.g. your organization)
Select the repositories you want to give access to (or Select all). These should be the same repositories that you have configured to sync with Flipt.
Set an expiration date
Select the following repository scopes (required):
- contents read and write access
- pull-requests read and write access
Click “Generate token” and copy the token. You will not be able to see it again!

2. Configure GitHub Credentials

Edit your Flipt configuration file to use the GitHub credentials you created in the previous step:

credentials:
  github:
    type: access_token
    access_token: <your-personal-access-token>

3. Configure Flipt Storage with GitHub Remote

Edit your Flipt configuration file to add or update the storage backend that syncs with your GitHub repository:

storage:
  github:
    remote: "https://github.com/<your-username>/<your-repo>.git"
    branch: "main"
    poll_interval: "30s"
    credentials: "github"
    backend:
      type: local
      path: "/path/to/local/clone"

4. Configure an Environment to use GitHub SCM

Edit your Flipt configuration file to add or update the environment that uses the GitHub SCM storage backend and add the scm section:

environments:
  production:
    name: "Production"
    storage: "github"
    default: true
    scm:
      type: github
      credentials: "github"

Bitbucket Integration

1. Create API Token or App Password

App passwords are being deprecated and will stop working in 2026. We strongly recommend using API tokens instead.

Option A: API Token (Recommended for Bitbucket Cloud)

Go to Bitbucket Account Settings > API tokens
Click “Create API token”
Give your token a name
Select the following scopes (required):
- Repositories: Read, Write
- Pull requests: Read, Write
Click “Create” and copy the generated token. You will not be able to see it again!

Option B: App Password (Legacy - Not recommended)

Only use app passwords if API tokens are not available. App passwords will be deprecated on September 9, 2025 and will stop working on June 9, 2026.

Go to Bitbucket Account Settings > App passwords
Click “Create app password”
Give your app password a name
Select the following permissions (required):
- Repositories: Read, Write
- Pull requests: Read, Write
Click “Create” and copy the generated password. You will not be able to see it again!

Option C: Access Token (For Bitbucket Server/Data Center)

Go to your Bitbucket Server settings
Navigate to Personal access tokens
Create a new token with repository and pull request permissions

2. Configure Bitbucket Credentials

Edit your Flipt configuration file to use the Bitbucket credentials:Using API Token (Recommended):

credentials:
  bitbucket:
    type: access_token
    access_token: <your-api-token>

Using App Password (Legacy):

credentials:
  bitbucket:
    type: basic
    basic:
      username: <your-bitbucket-username>
      password: <your-app-password>

Using Access Token (Bitbucket Server/Data Center):

credentials:
  bitbucket:
    type: access_token
    access_token: <your-access-token>

3. Configure Flipt Storage with Bitbucket Remote

Edit your Flipt configuration file to add or update the storage backend that syncs with your Bitbucket repository:

storage:
  bitbucket:
    remote: "https://bitbucket.org/<your-username>/<your-repo>.git"
    branch: "main"
    poll_interval: "30s"
    credentials: "bitbucket"
    backend:
      type: local
      path: "/path/to/local/clone"

4. Configure an Environment to use Bitbucket SCM

Edit your Flipt configuration file to add or update the environment that uses the Bitbucket SCM storage backend and add the scm section:

environments:
  production:
    name: "Production"
    storage: "bitbucket"
    default: true
    scm:
      type: bitbucket
      credentials: "bitbucket"

For Bitbucket Server (Custom Instance):

environments:
  production:
    name: "Production"
    storage: "bitbucket"
    default: true
    scm:
      type: bitbucket
      api_url: "https://bitbucket.company.com/api/v2.0"
      credentials: "bitbucket"

Azure DevOps Integration

1. Create a Personal Access Token (PAT)

Go to your Azure DevOps organization (e.g., https://dev.azure.com/{your-organization})
Click on your profile picture in the top right corner
Select “Personal access tokens”
Click “New Token”
Give your token a name and set an expiration date
Select the organization and scope:
- Code (read & write) - Required for repository access
- Pull Request (read & write) - Required for merge proposals
Click “Create” and copy the token. You will not be able to see it again!

2. Configure Azure DevOps Credentials

Edit your Flipt configuration file to use the Azure DevOps credentials:

credentials:
  azure:
    type: basic
    basic:
      username: <your-username-or-email>
      password: <your-personal-access-token>

3. Configure Flipt Storage with Azure DevOps Remote

Edit your Flipt configuration file to add or update the storage backend that syncs with your Azure DevOps repository:

storage:
  azure:
    remote: "https://dev.azure.com/<your-org>/<your-project>/_git/<your-repo>"
    branch: "main"
    poll_interval: "30s"
    credentials: "azure"
    backend:
      type: local
      path: "/path/to/local/clone"

4. Configure an Environment to use Azure DevOps SCM

Edit your Flipt configuration file to add or update the environment that uses the Azure DevOps SCM storage backend:

environments:
  production:
    name: "Production"
    storage: "azure"
    default: true
    scm:
      type: azure
      credentials: "azure"

For Azure DevOps Server (On-premises):

environments:
  production:
    name: "Production"
    storage: "azure"
    default: true
    scm:
      type: azure
      api_url: "https://your-server/tfs/{collection}/_apis"
      credentials: "azure"

GitLab Integration

1. Create a Personal Access Token (PAT)

Go to GitLab Settings > Access Tokens (or your GitLab instance)
Click “Add new token”
Give your token a name
Set an expiration date (optional but recommended)
Select the following scopes (required):
- api - Full access to the API
- read_repository - Read access to repositories
- write_repository - Write access to repositories
Click “Create personal access token” and copy the token. You will not be able to see it again!

2. Configure GitLab Credentials

Edit your Flipt configuration file to use the GitLab credentials:

credentials:
  gitlab:
    type: access_token
    access_token: <your-personal-access-token>

3. Configure Flipt Storage with GitLab Remote

Edit your Flipt configuration file to add or update the storage backend that syncs with your GitLab repository:

storage:
  gitlab:
    remote: "https://gitlab.com/<your-username>/<your-repo>.git"
    branch: "main"
    poll_interval: "30s"
    credentials: "gitlab"
    backend:
      type: local
      path: "/path/to/local/clone"

4. Configure an Environment to use GitLab SCM

Edit your Flipt configuration file to add or update the environment that uses the GitLab SCM storage backend:

environments:
  production:
    name: "Production"
    storage: "gitlab"
    default: true
    scm:
      type: gitlab
      credentials: "gitlab"

For GitLab Self-Managed (Self-hosted):

environments:
  production:
    name: "Production"
    storage: "gitlab"
    default: true
    scm:
      type: gitlab
      api_url: "https://gitlab.company.com/api/v4"
      credentials: "gitlab"

2. Start Flipt

Start or restart your Flipt server with the updated configuration. Flipt will now:

Clone your Git repository to the specified local path
Periodically sync flag state to and from your Git provider
Commit and push changes when you update flags via the Flipt API or UI
Enable merge proposals in the Flipt UI

3. Troubleshooting

Common Issues

Authentication: Ensure your credentials (PAT, API token, or app password) have the correct permissions and haven’t expired
Permissions: Make sure the local path is writable by the Flipt process
Logs: Check Flipt logs for any sync or authentication errors
Network: For self-hosted instances, verify the API URL is correct and accessible

Provider-Specific Troubleshooting

GitHub:

Ensure your PAT has the correct repository scopes (contents and pull-requests)
Verify the repository URL format: https://github.com/{owner}/{repo}.git

Bitbucket:

For API tokens: Ensure you have Repositories: Read, Write and Pull requests: Read, Write scopes
For app passwords: Note that they will be deprecated in September 2025
For Bitbucket Server/Data Center: Verify the API URL format (typically /api/v2.0)

Azure DevOps:

Ensure your PAT has Code (read & write) and Pull Request (read & write) scopes
Verify the repository URL format: https://dev.azure.com/{org}/{project}/_git/{repo}
For Azure DevOps Server: Verify the API URL format: https://your-server/tfs/{collection}/_apis

GitLab:

Ensure your PAT has the correct scopes: api, read_repository, write_repository
For GitLab Self-Managed: Verify the API URL is correct (typically /api/v4)
Verify the repository URL format: https://gitlab.com/{owner}/{repo}.git

Authentication Formats by Provider

Different Git providers require different authentication formats for optimal compatibility:

Provider	Recommended Auth Method	Basic Auth Format	Notes
GitHub	Personal Access Token	Username: token, Password: (empty)
GitLab	Personal Access Token	Username: oauth2, Password: token
Bitbucket	API Token	Username: (not used), Token: api_token	App passwords deprecated Sept 2025
Azure DevOps	Personal Access Token	Username: username, Password: PAT
Gitea	Personal Access Token	Username: token, Password: (empty)

Conclusion

This guide showed how to configure Flipt to enable merge proposals in the Flipt UI. You can now use Flipt to manage your flags and use merge proposals to review and approve changes to your flags. If you have any questions or feedback, please reach out to the Flipt team on Discord or GitHub Discussions.

References:

Getting Started

Pro Features

Configuration

Integration

CLI

Guides

Tooling

Git SCM Integration

Prerequisites

1. Configure SCM Integration

GitHub Integration

1. Create a Personal Access Token (PAT)

2. Configure GitHub Credentials

3. Configure Flipt Storage with GitHub Remote

4. Configure an Environment to use GitHub SCM

Bitbucket Integration

1. Create API Token or App Password

2. Configure Bitbucket Credentials

3. Configure Flipt Storage with Bitbucket Remote

4. Configure an Environment to use Bitbucket SCM

Azure DevOps Integration

1. Create a Personal Access Token (PAT)

2. Configure Azure DevOps Credentials

3. Configure Flipt Storage with Azure DevOps Remote

4. Configure an Environment to use Azure DevOps SCM

GitLab Integration

1. Create a Personal Access Token (PAT)

2. Configure GitLab Credentials

3. Configure Flipt Storage with GitLab Remote

4. Configure an Environment to use GitLab SCM

2. Start Flipt

3. Troubleshooting

Common Issues

Provider-Specific Troubleshooting

Authentication Formats by Provider

Conclusion

Getting Started

Pro Features

Configuration

Integration

CLI

Guides

Tooling

​Prerequisites

​1. Configure SCM Integration

​GitHub Integration

​1. Create a Personal Access Token (PAT)

​2. Configure GitHub Credentials

​3. Configure Flipt Storage with GitHub Remote

​4. Configure an Environment to use GitHub SCM

​Bitbucket Integration

​1. Create API Token or App Password

​2. Configure Bitbucket Credentials

​3. Configure Flipt Storage with Bitbucket Remote

​4. Configure an Environment to use Bitbucket SCM

​Azure DevOps Integration

​1. Create a Personal Access Token (PAT)

​2. Configure Azure DevOps Credentials

​3. Configure Flipt Storage with Azure DevOps Remote

​4. Configure an Environment to use Azure DevOps SCM

​GitLab Integration

​1. Create a Personal Access Token (PAT)

​2. Configure GitLab Credentials

​3. Configure Flipt Storage with GitLab Remote

​4. Configure an Environment to use GitLab SCM

​2. Start Flipt

​3. Troubleshooting

​Common Issues

​Provider-Specific Troubleshooting

​Authentication Formats by Provider

​Conclusion

Prerequisites

1. Configure SCM Integration

GitHub Integration

1. Create a Personal Access Token (PAT)

2. Configure GitHub Credentials

3. Configure Flipt Storage with GitHub Remote

4. Configure an Environment to use GitHub SCM

Bitbucket Integration

1. Create API Token or App Password

2. Configure Bitbucket Credentials

3. Configure Flipt Storage with Bitbucket Remote

4. Configure an Environment to use Bitbucket SCM

Azure DevOps Integration

1. Create a Personal Access Token (PAT)

2. Configure Azure DevOps Credentials

3. Configure Flipt Storage with Azure DevOps Remote

4. Configure an Environment to use Azure DevOps SCM

GitLab Integration

1. Create a Personal Access Token (PAT)

2. Configure GitLab Credentials

3. Configure Flipt Storage with GitLab Remote

4. Configure an Environment to use GitLab SCM

2. Start Flipt

3. Troubleshooting

Common Issues

Provider-Specific Troubleshooting

Authentication Formats by Provider

Conclusion