Secrets¶
xfg can sync GitHub Actions secrets to your repositories using the xfg secrets sync command. Secrets live under settings: and their values are read from environment variables at runtime. Like variables, they can be scoped at the root, group, conditional-group, and per-repo level.
Secrets are never touched by a plain xfg sync — only xfg secrets sync reads them.
GitHub-Only Feature
Secrets are only available for GitHub repositories. Azure DevOps and GitLab repos will be skipped when running xfg secrets sync.
Quick Start¶
id: my-config
settings:
secrets:
MY_API_KEY:
env: MY_API_KEY_VALUE
DATABASE_URL:
env: DATABASE_URL_VALUE
DEPLOY_TOKEN:
env: DEPLOY_TOKEN_VALUE
repos:
- git: git@github.com:your-org/your-repo.git
- git: git@github.com:your-org/another-repo.git
# Preview changes (dry-run)
MY_API_KEY_VALUE=abc123 DATABASE_URL_VALUE=postgres://... DEPLOY_TOKEN_VALUE=tok_xyz \
xfg secrets sync -c config.yaml --dry-run
# Apply secrets
MY_API_KEY_VALUE=abc123 DATABASE_URL_VALUE=postgres://... DEPLOY_TOKEN_VALUE=tok_xyz \
xfg secrets sync -c config.yaml
Secret Config¶
Each secret entry maps a secret name (as it will appear in GitHub) to a SecretConfig object:
| Field | Required | Description |
|---|---|---|
env |
Yes | Name of the environment variable holding the value |
The secret name (MY_SECRET) is what gets created in GitHub Actions. The env field is the environment variable that xfg reads at runtime to get the actual secret value.
env can't name a credential xfg authenticates with (GH_TOKEN, GITHUB_TOKEN, XFG_GITHUB_APP_PRIVATE_KEY and the others listed in Environment Variables). To push one of those values as a secret on purpose, export it under another name.
Scoping Secrets¶
Secrets merge through the same layers as variables: root → group → conditional group → repo. Innermost wins.
id: my-config
settings:
secrets:
SHARED_KEY:
env: SHARED_KEY_VALUE
groups:
frontend:
settings:
secrets:
NPM_TOKEN:
env: NPM_TOKEN_VALUE
repos:
# Gets SHARED_KEY and NPM_TOKEN
- git: git@github.com:your-org/web.git
groups: [frontend]
# Gets SHARED_KEY only
- git: git@github.com:your-org/api.git
# Gets DEPLOY_KEY only — inherit: false discards everything above
- git: git@github.com:your-org/isolated.git
groups: [frontend]
settings:
secrets:
inherit: false
DEPLOY_KEY:
env: ISOLATED_DEPLOY_KEY
# Gets nothing — SHARED_KEY is opted out by name
- git: git@github.com:your-org/legacy.git
settings:
secrets:
SHARED_KEY: false
| Directive | Effect |
|---|---|
inherit: false |
Discard every inherited secret at this layer |
NAME: false |
Opt out of one inherited secret |
deleteOrphaned |
Innermost wins; inherit: false drops an inherited one |
deleteOrphaned is an ordinary field, not an entry: the innermost layer that sets it wins. inherit: false discards the inherited secrets and an inherited deleteOrphaned along with them, so a layer that wants cleanup must set deleteOrphaned: true itself.
inherit: false plus deleteOrphaned: true deletes inherited secrets
inherit: false makes inherited secrets undesired, and deleteOrphaned: true set in the same layer removes undesired secrets. Together they delete those secrets from the repo, as in the example below. That is correct behaviour, but the interaction is easy to miss — run --dry-run first.
id: secrets
settings:
secrets:
SHARED_KEY:
env: SHARED
repos:
- git: git@github.com:org/isolated.git
settings:
secrets:
inherit: false # SHARED_KEY is not in this repo's config
deleteOrphaned: true # ...so it gets deleted from the repo
OWN_KEY:
env: OWN
Secret Naming Rules¶
Secret names must match [A-Za-z_][A-Za-z0-9_]* and may not start with GITHUB_ (reserved by GitHub).
Valid examples:
Invalid examples (will be rejected):
settings:
secrets:
GITHUB_TOKEN: # Reserved prefix
env: TOKEN
MY-SECRET: # Hyphens not allowed
env: SECRET
Case-Insensitive Matching¶
Secret name matching is case-insensitive (GitHub treats secret names as case-insensitive). Defining MY_SECRET and my_secret in the same config is rejected as a duplicate. xfg normalizes names to uppercase when comparing against remote state.
Environment Variable Requirements¶
Secret values are never stored in your config file. They are read from environment variables at runtime, so you must export them before running xfg secrets sync:
In CI/CD, inject secrets as environment variables to the step running xfg:
# GitHub Actions example
- name: Sync secrets
uses: anthony-spruyt/xfg@v9 # x-release-please-major
with:
command: secrets-sync
config: config.yaml
github-client-id: ${{ vars.APP_CLIENT_ID }}
github-app-private-key: ${{ secrets.APP_PRIVATE_KEY }}
env:
MY_API_KEY_VALUE: ${{ secrets.MY_API_KEY_VALUE }}
DATABASE_URL_VALUE: ${{ secrets.DATABASE_URL_VALUE }}
Authentication¶
With XFG_GITHUB_CLIENT_ID and XFG_GITHUB_APP_PRIVATE_KEY set, xfg secrets sync mints a GitHub App token per repo owner. A repo whose owner has no installation fails the run, so a missed rotation is never silent. Without app credentials it uses GH_TOKEN, then GITHUB_TOKEN. See GitHub App.
The app needs the Secrets: Read and write repository permission for repo secrets. Environment secrets need Environments: Read and write, and finding an environment needs Actions: Read.
Encryption¶
Secret values are encrypted using libsodium sealed box encryption before being sent to the GitHub API. xfg:
- Fetches the repository's public key from GitHub
- Encrypts the secret value using that public key (libsodium sealed box)
- Uploads the encrypted value — GitHub decrypts it server-side
The plaintext value never leaves your environment unencrypted.
Security: Secret values are never logged
xfg never logs, prints, or stores secret values. Only secret names appear in output. If you see a secret value in output, please open an issue.
Deleting Orphaned Secrets¶
When deleteOrphaned: true is set, secrets not present in the config will be deleted from the repository:
Danger
deleteOrphaned deletes all secrets from the repository that are not defined in your config, including secrets created manually or by other tools. Use with caution.
Dry Run Output¶
Every run lists each secret it creates, updates or deletes, per repo. With --dry-run nothing is written:
[1/2] ✓ your-org/frontend: Secrets: [DRY RUN] 2 created, 1 updated, 1 deleted
+ secret "MY_API_KEY"
+ secret "DATABASE_URL"
~ secret "DEPLOY_TOKEN" (update, value write-only)
- secret "OLD_TOKEN"
Plan: 4 secrets (2 to create, 1 to update, 1 to delete)
Without --dry-run the first line reads Secrets: Applied: ..., the same list follows, and the last line reads Applied: 4 secrets (2 created, 1 updated, 1 deleted).
If a write fails partway, the run fails and the list shows only the secrets already written. Those writes are not rolled back.
Existing secrets always show as update. GitHub never returns secret values, so xfg cannot tell whether a value changed and rewrites it every run.
A dry run for a repo that does not exist yet shows every configured secret as a create, since xfg sync creates the repo before secrets are written. Without --dry-run, a missing repo fails: run xfg sync first.
When GITHUB_STEP_SUMMARY is set, the same list is written to the job summary (## xfg Plan for a dry run, ## xfg Apply otherwise).
Secret values are never shown — only the secret names.
Environment Secrets¶
Secrets can also be scoped to a GitHub deployment environment under settings.environments.<name>.secrets. They use the same env config, are encrypted with the environment's own key, and are written only by xfg secrets sync. See GitHub Environments.
A workflow that xfg sync pushes in the run that creates its environment can start before these secrets are written. See the Quick Start.
Secrets Sync Command¶
See CLI Options — Secrets Sync Command for the full option list.
GitHub API Reference¶
Secrets are managed via the GitHub Actions Secrets API:
GET /repos/{owner}/{repo}/actions/secrets— List secrets (names only, not values)GET /repos/{owner}/{repo}/actions/secrets/public-key— Get encryption public keyPUT /repos/{owner}/{repo}/actions/secrets/{name}— Create or update a secretDELETE /repos/{owner}/{repo}/actions/secrets/{name}— Delete a secret