Overview#

Flipt v2 supports GPG commit signing to provide cryptographic verification of configuration changes. When enabled, Flipt automatically signs all commits to the flag configuration repository using a GPG key. These signatures can be verified by Git hosting services such as GitHub and GitLab, which display a "Verified" badge for signed commits. This feature ensures the authenticity and integrity of feature flag modifications and creates a verifiable audit trail for compliance and security purposes. Commit signing is available in Flipt Pro environments.

Prerequisites#

Before enabling commit signing, ensure you have:

• Flipt v2 with a Pro license or trial.
• A Flipt environment configured with Git Sync.
• Secrets management configured (e.g., HashiCorp Vault, Google Cloud Secret Manager, AWS Secrets Manager, Azure Key Vault, or file-based provider).
• A valid GPG key pair for signing.

Reference

GPG Key Generation and Management#

1. Generate a GPG Key#

Create a dedicated GPG key for Flipt:

gpg --full-generate-key
# Select RSA and RSA (default)
# Choose 4096 bits for maximum security
# Set expiration (recommended: 2 years)
# Enter details:
# Real name: Flipt Bot
# Email: flipt@yourcompany.com
# Comment: Flipt configuration signing

2. Export the Private Key#

Export the private key for storage in your secrets provider:

gpg --export-secret-keys --armor flipt@yourcompany.com > flipt-signing-key.asc
# Find your key ID with:
gpg --list-secret-keys flipt@yourcompany.com

3. Store the Private Key in Your Secrets Provider#

Store the exported private key securely in your chosen secrets provider.

Vault:

vault kv put secret/flipt/signing-key private_key=@flipt-signing-key.asc

Google Cloud Secret Manager:

gcloud secrets create flipt-signing-key --data-file=flipt-signing-key.asc

AWS Secrets Manager:

aws secretsmanager create-secret --name flipt-signing-key --secret-string "$(cat flipt-signing-key.asc)"

Azure Key Vault:

az keyvault secret set --vault-name your-vault-name --name flipt-signing-key --file flipt-signing-key.asc

File-based:

Store the key file in a secure location accessible to Flipt:

sudo mkdir -p /etc/flipt/secrets
sudo cp flipt-signing-key.asc /etc/flipt/secrets/signing-key
sudo chmod 600 /etc/flipt/secrets/signing-key

4. Upload the Public Key to Your Git Provider#

Export and upload the public key to your Git hosting service (e.g., GitHub):

gpg --export --armor flipt@yourcompany.com > flipt-public-key.asc

Add the contents of flipt-public-key.asc to your Git provider’s GPG keys section (for GitHub: Settings > SSH and GPG keys > New GPG key).

Reference

Configuring Commit Signing in Flipt#

YAML Configuration Example#

Add the following to your Flipt configuration file:

storage:
  default:
    signature:
      enabled: true
      type: "gpg"
      key_ref:
        provider: "vault" # Your secrets provider (vault, gcp, aws, azure, or file)
        path: "flipt/signing-key" # Path to private key in secrets
        key: "private_key" # Key name within the secret
      name: "Flipt Bot" # Signer name
      email: "flipt@yourcompany.com" # Signer email
      key_id: "flipt@yourcompany.com" # GPG key identifier

Environment Variable Configuration#

You can also configure commit signing using environment variables:

FLIPT_STORAGE_DEFAULT_SIGNATURE_ENABLED=true
FLIPT_STORAGE_DEFAULT_SIGNATURE_TYPE=gpg
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_PROVIDER=vault
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_PATH=flipt/signing-key
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_KEY=private_key
FLIPT_STORAGE_DEFAULT_SIGNATURE_NAME=Flipt Bot
FLIPT_STORAGE_DEFAULT_SIGNATURE_EMAIL=flipt@yourcompany.com
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_ID=flipt@yourcompany.com

Secrets Provider Configuration#

Configure your chosen secrets provider in your Flipt configuration.

Vault Provider:

secrets:
  providers:
    vault:
      enabled: true
      address: "https://vault.company.com"
      auth_method: "token"
      token: "hvs.your_vault_token"
      mount: "secret" # Default: secret

You can use environment variables to avoid storing sensitive values in configuration files:

export FLIPT_SECRETS_PROVIDERS_VAULT_TOKEN="hvs.your_vault_token"

Google Cloud Secret Manager Provider:

secrets:
  providers:
    gcp:
      enabled: true
      project: "my-gcp-project"
      credentials: "/path/to/service-account.json" # optional, defaults to Application Default Credentials

You can use environment variables:

FLIPT_SECRETS_PROVIDERS_GCP_ENABLED=true
FLIPT_SECRETS_PROVIDERS_GCP_PROJECT=my-gcp-project
FLIPT_SECRETS_PROVIDERS_GCP_CREDENTIALS=/path/to/service-account.json

File Provider:

secrets:
  providers:
    file:
      enabled: true
      base_path: "/etc/flipt/secrets"

AWS Secrets Manager Provider:

secrets:
  providers:
    aws:
      enabled: true
      endpoint_url: "" # Optional: for testing with LocalStack

AWS credentials and region are configured via IAM roles, environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION), or AWS config files following the AWS SDK's default credential provider chain.

You can use environment variables:

FLIPT_SECRETS_PROVIDERS_AWS_ENABLED=true
FLIPT_SECRETS_PROVIDERS_AWS_ENDPOINT_URL=http://localhost:4566

Azure Key Vault Provider:

secrets:
  providers:
    azure:
      enabled: true
      vault_url: "https://your-vault-name.vault.azure.net"

Azure Key Vault uses DefaultAzureCredential for authentication, which supports Managed Identity, environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET), Azure CLI authentication, and other credential sources.

You can use environment variables:

FLIPT_SECRETS_PROVIDERS_AZURE_ENABLED=true
FLIPT_SECRETS_PROVIDERS_AZURE_VAULT_URL=https://your-vault-name.vault.azure.net

Reference

How Commit Signing Works#

Once configured, Flipt retrieves the GPG private key from the configured secret provider (such as Vault, Google Cloud Secret Manager, AWS Secrets Manager, Azure Key Vault, or file-based storage) and uses it to sign all Git commits made to the flag configuration repository. The signature includes the configured signer name, email, and key ID. Signed commits can be verified by your Git provider and locally using Git.

Reference

Verifying Signed Commits#

To verify that commits are being signed:

git log --show-signature -5
git verify-commit HEAD

On GitHub and similar platforms, look for the "Verified" badge next to commits. Clicking the badge will show signature and key details.

Troubleshooting#

Commits Not Showing as Verified

• Ensure the public key is uploaded to your Git hosting service.
• The email in the GPG key must match the configured email.
• The GPG key must be valid and not expired.
• The key_id must match your actual GPG key.

Signing Failures

Error: failed to sign commit: gpg key not found

• Verify the key exists in your secrets provider.
• Check the key reference path and key name.
• Ensure the secrets provider is accessible.

Key Loading Errors

Error: failed to load GPG private key

• Verify secrets provider connectivity.
• Check authentication credentials.
• Ensure the private key is in valid ASCII armored format.

Permission Errors

Error: insufficient permissions to access secret

• Ensure Flipt has the necessary permissions in your secrets provider.
• Check authentication method configuration.
• Review access policies for the signing key secret.

Debugging

Enable debug logging in Flipt to assist with troubleshooting:

log:
  level: "debug"

Validation Commands

Test your GPG key setup:

gpg --import /path/to/private-key.asc
gpg --list-secret-keys flipt@yourcompany.com
echo "test" | gpg --armor --sign --default-key flipt@yourcompany.com

Reference

Security Considerations#

• Store the GPG private key only in a secure secrets provider (such as Vault, Google Cloud Secret Manager, AWS Secrets Manager, Azure Key Vault, or file-based storage with appropriate permissions).
• Restrict access to the signing key using provider access controls and policies.
• Never expose the private key in configuration files or version control.
• Ensure the public key is uploaded to your Git provider for signature verification.
• Rotate signing keys periodically and update the configuration as needed.

Reference