Manage feature flags as code with API automation, CI/CD pipelines, and version-controlled configurations
Last updated November 21, 2026
Infrastructure as Code
Manage your feature flags as code alongside your application. Use Flaggr's API to automate flag creation, promote configurations between environments, validate changes in CI/CD, and maintain flag definitions in version control.
Why IaC for Feature Flags?
| Benefit | How |
|---|---|
| Reproducibility | Flag configurations are version-controlled and can be recreated from scratch |
| Auditability | Changes go through pull requests with code review |
| Consistency | Same flags across environments, applied automatically |
| Rollback | Git revert restores previous flag state |
| Testing | Validate flag configurations before applying them |
API-Driven Automation
All flag operations are available through the REST API. Use a project API token for one project's jobs, or a personal access token for automation across projects.
Creating a Token for CI/CD
Create the token in the dashboard under Settings → API tokens. The API (POST /api/projects/{id}/tokens on https://flaggr.dev) takes the same choices, but only from a signed-in dashboard session or an admin-tier MCP connector: API tokens and personal access tokens can't create tokens (403). A pipeline that syncs flags needs read and write, not delete:
{
"name": "CI/CD Pipeline",
"permissions": { "read": true, "write": true, "delete": false },
"expiresAt": "2027-01-01T00:00:00Z"
}With scopes instead of permissions and "tokenType": "opaque", the token is a long-lived scoped token limited to what the scopes name. A service scope takes the service's ID, not its slug:
{
"name": "CI/CD Pipeline (web-app)",
"tokenType": "opaque",
"scopes": ["service:<service id>:write"],
"expiresAt": "2027-01-01T00:00:00Z"
}Give CI/CD tokens only what the job needs: limit them to the services they change and leave out delete. Rotate tokens regularly.
A service-scoped token works on the routes that name its service: GET /api/flags?projectId=…&serviceId=…, creating flags in that service, POST /api/flags/import, bulk changes and GET /api/flags/export?serviceId=…. It can't list or export the whole project. Without "tokenType": "opaque", a scopes body makes a legacy JWT whose access token lasts 5 minutes, so for a long-lived CI secret use an opaque token (fgr_…) or a personal access token. Imports never write to an environment that requires approval: those items come back in errors with code: "APPROVAL_REQUIRED" — promote them instead.
Flag Definitions in Version Control
Store your flag definitions as JSON files in your repository:
repo/
├── flags/
│ ├── development.json
│ ├── staging.json
│ └── production.json
└── .github/
└── workflows/
└── sync-flags.yml
Flag Definition File
{
"flags": [
{
"key": "checkout-v2",
"name": "Checkout V2",
"description": "New streamlined checkout flow",
"type": "boolean",
"enabled": false,
"defaultValue": false,
"serviceId": "web-app",
"environment": "production",
"tags": ["checkout", "q1-2026"],
"targeting": [
{
"id": "beta-users",
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" }
],
"rolloutPercentage": 100,
"value": true
}
]
},
{
"key": "dark-mode",
"name": "Dark Mode",
"description": "Toggle dark mode support",
"type": "boolean",
"enabled": true,
"defaultValue": false,
"serviceId": "web-app",
"environment": "production",
"tags": ["ui", "permanent"]
}
]
}CI/CD Pipeline Examples
GitHub Actions: Validate and Sync Flags
name: Sync Feature Flags
on:
push:
branches: [main]
paths:
- 'flags/**'
pull_request:
paths:
- 'flags/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate flag definitions
run: |
for file in flags/*.json; do
echo "Validating $file..."
# Validate JSON syntax
jq empty "$file" || exit 1
# Validate required fields
jq -e '.flags | length > 0' "$file" > /dev/null || {
echo "Error: $file has no flags"
exit 1
}
# Validate flag keys match naming convention
jq -e '.flags[] | select(.key | test("^[a-zA-Z][a-zA-Z0-9_-]*$") | not) | .key' "$file" \
| while read -r key; do
echo "Error: Invalid flag key: $key"
exit 1
done
done
echo "All flag definitions valid"
- name: Dry run import (PR only)
if: github.event_name == 'pull_request'
env:
FLAGGR_API_URL: ${{ vars.FLAGGR_API_URL }}
FLAGGR_TOKEN: ${{ secrets.FLAGGR_CI_VALIDATION_TOKEN }}
run: |
for file in flags/*.json; do
echo "Dry run: $file"
RESULT=$(jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' "$file" |
curl -s -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @-)
echo "$RESULT" | jq .
ERRORS=$(echo "$RESULT" | jq '.errors | length')
if [ "$ERRORS" -gt 0 ]; then
echo "::error::Import validation failed with $ERRORS errors"
exit 1
fi
done
sync:
needs: validate
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
# Keep FLAGGR_CI_SYNC_TOKEN in this GitHub environment, and allow only
# main to deploy to it, so jobs on other branches can't read the token.
environment: flaggr-sync
steps:
- uses: actions/checkout@v4
- name: Sync flags to Flaggr
env:
FLAGGR_API_URL: ${{ vars.FLAGGR_API_URL }}
FLAGGR_TOKEN: ${{ secrets.FLAGGR_CI_SYNC_TOKEN }}
run: |
for file in flags/*.json; do
echo "Syncing $file..."
RESULT=$(jq '{flags: .flags, conflictResolution: "overwrite", dryRun: false}' "$file" |
curl -s -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @-)
echo "$RESULT" | jq .
SUCCESS=$(echo "$RESULT" | jq '.success')
if [ "$SUCCESS" != "true" ]; then
echo "::error::Flag sync failed"
exit 1
fi
done
echo "All flags synced successfully"Generic Bash Script
A reusable script for any CI/CD system:
#!/bin/bash
# sync-flags.sh — Sync flag definitions to Flaggr
set -euo pipefail
FLAGGR_API_URL="${FLAGGR_API_URL:?Missing FLAGGR_API_URL}"
FLAGGR_TOKEN="${FLAGGR_TOKEN:?Missing FLAGGR_TOKEN}"
FLAGS_DIR="${FLAGS_DIR:-./flags}"
DRY_RUN="${DRY_RUN:-false}"
CONFLICT="${CONFLICT:-skip}"
for file in "$FLAGS_DIR"/*.json; do
[ -f "$file" ] || continue
echo "Processing: $file"
RESULT=$(jq --arg cr "$CONFLICT" --argjson dr "$DRY_RUN" \
'{flags: .flags, conflictResolution: $cr, dryRun: $dr}' "$file" |
curl -sf -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @-)
CREATED=$(echo "$RESULT" | jq '.created')
UPDATED=$(echo "$RESULT" | jq '.updated')
SKIPPED=$(echo "$RESULT" | jq '.skipped')
ERRORS=$(echo "$RESULT" | jq '.errors | length')
echo " Created: $CREATED, Updated: $UPDATED, Skipped: $SKIPPED, Errors: $ERRORS"
if [ "$ERRORS" -gt 0 ]; then
echo "$RESULT" | jq '.errors[]'
exit 1
fi
done
echo "Done"Usage:
# Dry run
DRY_RUN=true CONFLICT=skip ./sync-flags.sh
# Sync with overwrite
DRY_RUN=false CONFLICT=overwrite ./sync-flags.shEnvironment Promotion
Automate flag promotion from staging to production:
#!/bin/bash
# promote-flags.sh — Promote flags from staging to production
set -euo pipefail
FLAGGR_API_URL="${FLAGGR_API_URL:?Missing FLAGGR_API_URL}"
FLAGGR_TOKEN="${FLAGGR_TOKEN:?Missing FLAGGR_TOKEN}"
PROJECT_ID="${PROJECT_ID:?Missing PROJECT_ID}"
# 1. Export from staging
echo "Exporting staging flags..."
curl -sf "${FLAGGR_API_URL}/api/flags/export?projectId=${PROJECT_ID}&environment=staging" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-o staging-export.json
# 2. Transform for production (disabled by default for safety)
echo "Transforming for production..."
jq '.flags |= map(.environment = "production" | .enabled = false)' \
staging-export.json > production-import.json
FLAG_COUNT=$(jq '.flags | length' production-import.json)
echo " $FLAG_COUNT flags to promote"
# 3. Dry run
echo "Running dry run..."
RESULT=$(jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' production-import.json |
curl -sf -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @-)
echo "$RESULT" | jq '{created, updated, skipped, errors: (.errors | length)}'
# 4. Confirm and apply
read -p "Apply to production? (yes/no): " CONFIRM
if [ "$CONFIRM" = "yes" ]; then
jq '{flags: .flags, conflictResolution: "skip", dryRun: false}' production-import.json |
curl -sf -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @- | jq .
echo "Promotion complete"
else
echo "Cancelled"
fi
# Cleanup
rm -f staging-export.json production-import.jsonPR Validation with Dry Run
Add flag validation to your PR checks to catch issues before merge:
# .github/workflows/validate-flags.yml
name: Validate Flags
on:
pull_request:
paths: ['flags/**']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate and dry-run import
env:
FLAGGR_API_URL: ${{ vars.FLAGGR_API_URL }}
FLAGGR_TOKEN: ${{ secrets.FLAGGR_CI_VALIDATION_TOKEN }}
run: |
# Find changed flag files
CHANGED=$(git diff --name-only origin/main -- 'flags/*.json')
if [ -z "$CHANGED" ]; then
echo "No flag files changed"
exit 0
fi
for file in $CHANGED; do
echo "::group::Validating $file"
RESULT=$(jq '{flags: .flags, conflictResolution: "skip", dryRun: true}' "$file" |
curl -sf -X POST "${FLAGGR_API_URL}/api/flags/import" \
-H "Authorization: Bearer ${FLAGGR_TOKEN}" \
-H "Content-Type: application/json" \
--data-binary @-)
echo "$RESULT" | jq .
ERRORS=$(echo "$RESULT" | jq '.errors | length')
if [ "$ERRORS" -gt 0 ]; then
echo "::error::Validation failed for $file"
exit 1
fi
echo "::endgroup::"
done
- name: Comment on PR
if: success()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: 'Flag validation passed. All flag definitions are valid and ready to sync.'
})Token Management for CI/CD
Best Practices
| Practice | Why |
|---|---|
| Give each token only what its job needs | Limit blast radius if a token is compromised |
| Set expiration dates | Force periodic rotation |
| Store as CI/CD secrets | Never commit tokens to code |
| Separate validation and sync tokens | Revoke either on its own, and expose the sync token only to jobs on main |
| Rotate every 90 days | Reduce risk from leaked credentials |
Use a personal access token (fgp_…) for Terraform and cross-project scripts | One expiring, tier-capped account credential that SDKs never use |
Creating Purpose-Specific Tokens
Create one token per job (in the dashboard, or with POST /api/projects/{id}/tokens from a signed-in session, as above):
| Token | Job | permissions |
|---|---|---|
CI Validation | PR validation (dry-run imports), stored as the secret FLAGGR_CI_VALIDATION_TOKEN | { "read": true, "write": true, "delete": false } |
CI Flag Sync | Flag sync from main only, stored as FLAGGR_CI_SYNC_TOKEN in the flaggr-sync environment | { "read": true, "write": true, "delete": false } |
A dry-run import checks write access for every flag (items you can't write come back in errors), so the validation token needs write too, although a dry run changes nothing.
Terraform Provider
The Flaggr Terraform provider manages organizations, organization members, projects, environments, services, flags, metric sources, alert channels and alert rules. Its source and signed releases are public at github.com/flaggr-dev/terraform-provider-flaggr (latest release v0.1.1). Its source address is flaggr-dev/flaggr, but the Terraform Registry doesn't list it yet, so install it from the GitHub release for now (below). A provider in the Registry's flaggr namespace isn't Flaggr's; see official sources.
Authenticate with a personal access token: the write tier covers services, flags, alerts and metric sources in existing projects; organizations, organization members, environments, and creating or updating projects (any change to a flaggr_project, such as its name or description) need the admin tier; deleting projects or organizations (terraform destroy) also needs Allow owner actions and the owner role.
export FLAGGR_API_TOKEN="fgp_your_token_here"Installing from the GitHub release
Until the Registry lists the provider, put the release's zip in a local plugin directory, which terraform init checks before the Registry:
- From the v0.1.1 release, download
terraform-provider-flaggr_0.1.1_<os>_<arch>.zipfor each platform that runs Terraform, CI included, andterraform-provider-flaggr_0.1.1_SHA256SUMS. - Check the zips against the checksums:
sha256sum --ignore-missing -c terraform-provider-flaggr_0.1.1_SHA256SUMS(on macOS,shasum -a 256 --ignore-missing -c …). - Move the zips, unopened, to
~/.terraform.d/plugins/registry.terraform.io/flaggr-dev/flaggr/(on Windows,%APPDATA%\terraform.d\plugins\registry.terraform.io\flaggr-dev\flaggr\).
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/flaggr-dev/flaggr
mv terraform-provider-flaggr_0.1.1_linux_amd64.zip ~/.terraform.d/plugins/registry.terraform.io/flaggr-dev/flaggr/Terraform finds the provider there without any ~/.terraformrc setting, unless your CLI configuration has its own provider_installation block; then add the directory to it as a filesystem_mirror. If you commit .terraform.lock.hcl, record every platform's hash from the same directory: terraform providers lock -fs-mirror="$HOME/.terraform.d/plugins" -platform=linux_amd64 -platform=darwin_arm64 registry.terraform.io/flaggr-dev/flaggr. Name the provider as shown: with -fs-mirror and no provider named, the command looks for every provider in your configuration in that directory, and fails on the ones that aren't there.
Once the Registry lists flaggr-dev/flaggr, delete ~/.terraform.d/plugins/registry.terraform.io/flaggr-dev/flaggr (or the Windows directory above). While the provider is in that directory, Terraform installs it only from there and never checks the Registry for newer versions.
To work on the provider itself, clone it, build it with make build and point dev_overrides at the build, as its README's Development section describes.
Configuration
Every configuration needs the required_providers block: without it, terraform init looks for a hashicorp/flaggr provider, which doesn't exist.
terraform {
required_providers {
flaggr = {
source = "flaggr-dev/flaggr"
version = "~> 0.1"
}
}
}
# Reads FLAGGR_API_TOKEN from the environment.
provider "flaggr" {}
resource "flaggr_project" "main" {
name = "My Application"
slug = "my-app"
}
resource "flaggr_service" "web_app" {
project_id = flaggr_project.main.id
name = "Web App"
}
resource "flaggr_flag" "checkout_v2" {
project_id = flaggr_project.main.id
service_id = flaggr_service.web_app.id
key = "checkout-v2"
name = "Checkout V2"
type = "boolean"
enabled = false
default_value = jsonencode(false)
environment = "production"
}terraform plan refuses the reserved flag keys (bulk, create-from-nl, evaluate, evaluate-debug, export, import, stream) for flaggr_flag and data.flaggr_flag. Updating a flaggr_project sends only the changed fields, and nothing when nothing the API stores changed. Removing description clears it in Flaggr. A configuration without description also clears one set outside Terraform (for example in the dashboard) on the next apply; to keep it, set description or add lifecycle { ignore_changes = [description] }.
A project can't move to another organization, and a project in no organization can't be added to one: changing organization_id on an existing project fails at plan time with "A project can't move to another organization". Set it back to the project's organization, or remove it, which keeps the current one. To re-create the project in the other organization, run terraform taint flaggr_project.<name> and apply. This deletes the project and creates a new one with a new ID. terraform apply -replace and terraform destroy stop at the same check while organization_id names another organization, so set it back before destroying the project.
Earlier provider builds stored an empty ID for flaggr_project; re-import those resources with terraform import flaggr_project.<name> <project-id>.
Secrets inside flaggr_alert_channel and flaggr_metric_source config are returned only to admin-tier tokens; below admin, Flaggr returns them as "[redacted]". The provider keeps your configured values in state, so plans stay clean, but only an admin-tier token can detect a secret changed outside Terraform. See Secrets in config in the provider's documentation.
Related
- Import/Export — Export and import flag configurations
- API Tokens — Token types, scopes, and management
- Personal Access Tokens — Account-level tokens for Terraform and scripts
- Flag Lifecycle — Planning and retiring flags
- Versioning — Track changes and roll back
- REST API Reference — Complete endpoint reference