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 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 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 accesspull-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: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: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 thescm
section: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
andpull-requests
) - Verify the repository URL format:
https://github.com/{owner}/{repo}.git
- For API tokens: Ensure you have
Repositories: Read, Write
andPull 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
)
- Ensure your PAT has
Code (read & write)
andPull 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
- 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: