Guides

Config from CI

Keep config in your repository, check every pull request against the schema, push to staging on merge and promote to production with approval, using GitHub Actions and the hotcfg CLI.

Keep your config in the repository, next to the code that reads it. Then a config change gets the same review as a code change, and CI does the publishing:

  1. Pull request: CI pushes the file to development. The schema checks it, and any error shows up on the changed line of the pull request.
  2. Merge to main: CI pushes it to staging and writes the diff to the job summary.
  3. Release: someone runs the promote workflow. GitHub asks a reviewer to approve before it promotes staging to production.

A mistake that reaches production anyway is one rollback away, and apps get the fix on their next fetch.

What you need

  • A bin with a JSON Schema, so a bad file fails CI instead of reaching apps. Here it's mobile-flags in the organization acme.
  • The file in your repository, here config/flags.json.
  • Two secret API keys, created in the dashboard under Settings → API keys → Generate API key, each limited to the bin:
KeyEnvironmentsStored in GitHub as
CIdevelopment, stagingRepository secret HOTCFG_API_KEY
Promotestaging, productionSecret HOTCFG_API_KEY of the production environment

Promoting reads staging and writes production, so its key needs both. Only administrators change production, so an administrator (or the owner) creates the promote key; if they are later made a member, it stops working on production with 403 key_creator_not_admin until someone else rotates it. Give each key an expiry and put a reminder in your calendar to rotate it.

Limited keys are part of Pro. On Free every key can write every environment, so the repository's CI key could also change production: the reviewer step below then guards releases only by convention.

Set up the repository

  1. Settings → Secrets and variables → Actions → New repository secret: name HOTCFG_API_KEY, value the CI key.
  2. Settings → Environments → New environment: name it production. Under Deployment protection rules, tick Required reviewers and add the people who may release config. Under Environment secrets, add HOTCFG_API_KEY with the promote key.

A job that names environment: production gets that environment's secret instead of the repository's, and only after a reviewer approves. Jobs without it never see the production key.

Install the CLI on the runner

The CLI is one static binary. Download a pinned version and check it against the release's checksums, so a build never runs a binary it didn't expect:

step
- name: Install hotcfg
  env:
    HOTCFG_VERSION: "0.1.3"
  run: |
    base="https://github.com/hotcfg/cli/releases/download/v${HOTCFG_VERSION}"
    archive="hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz"
    curl -fsSLO "$base/$archive"
    curl -fsSLO "$base/checksums.txt"
    sha256sum --check --ignore-missing checksums.txt
    tar -xzf "$archive" hotcfg
    sudo install hotcfg /usr/local/bin/
    hotcfg version

This takes about a second. On an arm64 runner, use linux_arm64. Bump HOTCFG_VERSION when you want a newer CLI; see the changelog.

Check pull requests, push to staging on merge

.github/workflows/config.yml
name: Config

on:
  pull_request:
    paths: [config/flags.json]
  push:
    branches: [main]
    paths: [config/flags.json]

permissions:
  contents: read

# One push at a time per branch, so versions land in order.
concurrency:
  group: config-${{ github.ref }}

env:
  HOTCFG_VERSION: "0.1.3"
  HOTCFG_API_KEY: ${{ secrets.HOTCFG_API_KEY }}
  BIN: acme/mobile-flags

jobs:
  push:
    runs-on: ubuntu-latest
    # Pull requests from forks get no secrets; skip them.
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - uses: actions/checkout@v7

      - name: Install hotcfg
        run: |
          base="https://github.com/hotcfg/cli/releases/download/v${HOTCFG_VERSION}"
          archive="hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz"
          curl -fsSLO "$base/$archive"
          curl -fsSLO "$base/checksums.txt"
          sha256sum --check --ignore-missing checksums.txt
          tar -xzf "$archive" hotcfg
          sudo install hotcfg /usr/local/bin/

      - name: Push
        run: |
          env=development
          if [ "$GITHUB_EVENT_NAME" = push ]; then env=staging; fi
          if ! hotcfg push config/flags.json --bin "$BIN" --env "$env" 2> push.err; then
            cat push.err >&2
            # One annotation per schema error, on the line that broke it.
            awk '/^  [^ ]+:[0-9]+  /{split($1, a, ":"); file = a[1]; line = a[2]; ptr = $2}
                 /^    message: /{sub(/^    message: /, ""); printf "::error file=%s,line=%s::%s %s\n", file, line, ptr, $0}' push.err
            exit 1
          fi

          # Show what changed in the job summary.
          v=$(hotcfg history "$BIN" --env "$env" --json | jq .current_version)
          if [ "$v" -gt 1 ]; then
            {
              echo "### $BIN $env v$v"
              echo '```diff'
              hotcfg diff "$BIN" --env "$env" --from "$((v - 1))" --to "$v"
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
          fi

Warning

Always pass --env. hotcfg push writes to production when no environment is given. With the keys above, that mistake is refused with 403 key_scope_denied instead of reaching production.

When the schema refuses the file, the job fails with the error in its log, and the pull request shows it on the line:

job log
error: config/flags.json does not match the schema of bin acme/mobile-flags (1 error)

  config/flags.json:3  /limits/max_upload_mb
    rule:    /properties/limits/properties/max_upload_mb/type
    message: expected integer, but got string
::error file=config/flags.json,line=3::/limits/max_upload_mb expected integer, but got string

development is shared, so the most recent pull request's push is what's there. That's fine for checking files; apps under development can read it too.

Promote with approval

.github/workflows/promote.yml
name: Promote config

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  promote:
    runs-on: ubuntu-latest
    # Waits for a required reviewer, then gets the production environment's key.
    environment: production
    env:
      HOTCFG_VERSION: "0.1.3"
      HOTCFG_API_KEY: ${{ secrets.HOTCFG_API_KEY }}
      BIN: acme/mobile-flags
    steps:
      - name: Install hotcfg
        run: |
          base="https://github.com/hotcfg/cli/releases/download/v${HOTCFG_VERSION}"
          archive="hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz"
          curl -fsSLO "$base/$archive"
          curl -fsSLO "$base/checksums.txt"
          sha256sum --check --ignore-missing checksums.txt
          tar -xzf "$archive" hotcfg
          sudo install hotcfg /usr/local/bin/

      - run: hotcfg promote "$BIN" --from staging --to production

Run it from Actions → Promote config → Run workflow. The reviewer approves in the run's page, and the promote is recorded in the bin's history with the key's name, and in the audit log on Pro.

To undo, roll back from the dashboard, or with hotcfg rollback acme/mobile-flags --env production --to <version> using the same key.

Bundle live config into the app

The fetching recipes fall back to defaults shipped in the app the first time it runs offline. Fetch production while building the app, so those defaults are never far behind. A public bin needs no key:

step in your app's build
- name: Bundle current config as defaults
  run: hotcfg get acme/mobile-flags --env production > app/src/main/assets/flags.json

For a private bin, set HOTCFG_API_KEY to a publishable key limited to that bin and production.

You can also check config before you ship. Fail a release build that would be below the minimum version production asks for:

step in your app's build
- name: Check min_supported_version
  run: |
    min=$(hotcfg get acme/mobile-flags --env production --query .min_supported_version | jq -r .)
    if [ "$(printf '%s\n' "$min" "$APP_VERSION" | sort -V | head -n1)" != "$min" ]; then
      echo "::error::App version $APP_VERSION is below min_supported_version $min in production"
      exit 1
    fi

GitLab CI and others

The CLI runs anywhere with a shell. Store the key as a masked, protected variable named HOTCFG_API_KEY, then:

.gitlab-ci.yml
push-config:
  image: alpine:3.22
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [config/flags.json]
  variables:
    HOTCFG_VERSION: "0.1.3"
  script:
    - apk add --no-cache curl
    - base="https://github.com/hotcfg/cli/releases/download/v${HOTCFG_VERSION}"
    - curl -fsSLO "$base/hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz"
    - curl -fsSLO "$base/checksums.txt"
    - grep " hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz$" checksums.txt | sha256sum -c -
    - tar -xzf "hotcfg_${HOTCFG_VERSION}_linux_amd64.tar.gz" hotcfg
    - ./hotcfg push config/flags.json --bin acme/mobile-flags --env staging

Or skip the CLI and PUT the file. A schema error answers 422 with the details in JSON:

terminal
curl -fsS -X PUT "https://api.hotcfg.run/v1/acme/mobile-flags?env=staging" \
  -H "Authorization: Bearer $HOTCFG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @config/flags.json

Last updated 10 November 2026