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](https://hotcfg.run/docs/cli/rollback) away, and apps get the fix on their next fetch.

## What you need

- A bin with a [JSON Schema](https://hotcfg.run/docs/guides/schemas), 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](https://hotcfg.run/docs/reference/keys) to the bin:

| Key | Environments | Stored in GitHub as |
| --- | --- | --- |
| CI | `development`, `staging` | Repository secret `HOTCFG_API_KEY` |
| Promote | `staging`, `production` | Secret `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](https://hotcfg.run/docs/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](https://hotcfg.run/docs/account/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](https://hotcfg.run/docs/guides/fetching) 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
