Git SCM Integration

​

Prerequisites

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

​

1. Configure SCM Integration

• GitHub
• BitBucket
• Azure DevOps
• GitLab

​

GitHub Integration

​

1. Create a Personal Access Token (PAT)

1. Go to GitHub Settings > Developer settings > Personal access tokens.
2. Click “Generate new token”
3. Give your token a name
4. Select a resource owner (e.g. your organization)
5. 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.
6. Set an expiration date
7. Select the following repository scopes (required):
   • contents read and write access
   • pull-requests read and write access

8. 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:

Copy

Ask AI

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:

Copy

Ask AI

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:

Copy

Ask AI

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

​

2. Start Flipt

• 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

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

• 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)

• 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

• 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

​

Conclusion

• Flipt v2 Environments Configuration
• Flipt v2 Git Sync
• Flipt v2 Merge Proposals
• GitHub: Creating a personal access token