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:
- 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. - Merge to
main: CI pushes it tostagingand writes the diff to the job summary. - 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-flagsin the organizationacme. - 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:
| 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
- Settings → Secrets and variables → Actions → New repository secret: name
HOTCFG_API_KEY, value the CI key. - 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, addHOTCFG_API_KEYwith 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:
- 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 versionThis 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
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"
fiWarning
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:
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 stringdevelopment 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
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 productionRun 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:
- name: Bundle current config as defaults
run: hotcfg get acme/mobile-flags --env production > app/src/main/assets/flags.jsonFor 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:
- 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
fiGitLab CI and others
The CLI runs anywhere with a shell. Store the key as a masked, protected variable named HOTCFG_API_KEY, then:
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 stagingOr skip the CLI and PUT the file. A schema error answers 422 with the details in JSON:
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.jsonLast updated 10 November 2026