Skip to main content

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?

BenefitHow
ReproducibilityFlag configurations are version-controlled and can be recreated from scratch
AuditabilityChanges go through pull requests with code review
ConsistencySame flags across environments, applied automatically
RollbackGit revert restores previous flag state
TestingValidate 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"
}
Info

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.sh

Environment 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.json

PR 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

PracticeWhy
Give each token only what its job needsLimit blast radius if a token is compromised
Set expiration datesForce periodic rotation
Store as CI/CD secretsNever commit tokens to code
Separate validation and sync tokensRevoke either on its own, and expose the sync token only to jobs on main
Rotate every 90 daysReduce risk from leaked credentials
Use a personal access token (fgp_…) for Terraform and cross-project scriptsOne 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):

TokenJobpermissions
CI ValidationPR validation (dry-run imports), stored as the secret FLAGGR_CI_VALIDATION_TOKEN{ "read": true, "write": true, "delete": false }
CI Flag SyncFlag 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:

  1. From the v0.1.1 release, download terraform-provider-flaggr_0.1.1_<os>_<arch>.zip for each platform that runs Terraform, CI included, and terraform-provider-flaggr_0.1.1_SHA256SUMS.
  2. 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 …).
  3. 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.