Migrating from v6 to v7¶
v7 moves secrets: under settings:, so secrets can be scoped per group and per repo instead of being pushed to every repo in the config.
Breaking Changes¶
1. Root-level secrets: moves under settings:¶
Before (v6):
id: my-config
secrets:
MY_KEY:
env: MY_KEY_VALUE
repos:
- git: git@github.com:org/web.git
- git: git@github.com:org/api.git
After (v7):
id: my-config
settings:
secrets:
MY_KEY:
env: MY_KEY_VALUE
repos:
- git: git@github.com:org/web.git
- git: git@github.com:org/api.git
There is no back-compat shim. A root-level secrets: block produces:
Root-level 'secrets' is no longer supported — move it under 'settings.secrets'.
Secrets can now also be scoped per group and per repo.
See https://anthony-spruyt.github.io/xfg/migration-v7/
Your editor will not flag this
The config schema's root object does not set additionalProperties: false, so a stale root-level secrets: block will not be underlined in your editor. The validation error above is the only signal you get.
2. Secrets can now be scoped¶
This is the point of the change. 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:
- git: git@github.com:org/web.git
groups: [frontend] # SHARED_KEY + NPM_TOKEN
- git: git@github.com:org/api.git
settings:
secrets:
MY_KEY: false # opt out of one inherited secret
- git: git@github.com:org/isolated.git
settings:
secrets:
inherit: false # discard all inherited secrets
DEPLOY_KEY:
env: ISOLATED_DEPLOY_KEY
See Secrets for the full reference, including the inherit: false + deleteOrphaned: true interaction.
3. Group-level variables.inherit: false no longer clears deleteOrphaned¶
deleteOrphaned is a policy switch, not an entry. The repo layer already treated it that way; the group layer did not. Both now behave the same: inherit: false discards inherited entries only.
v6 behaviour: root variables.deleteOrphaned: true + a group with variables: { inherit: false, ... } silently disabled orphan deletion for that group.
v7 behaviour: deleteOrphaned: true stays on.
To opt out, set it explicitly:
groups:
myGroup:
settings:
variables:
inherit: false
deleteOrphaned: false # was implicit in v6, now required
MY_VAR: "value"
The same rule applies to the new settings.secrets.
4. Split config folders: only root settings: is single-file¶
In a split config folder, root-level settings: — and therefore any root-level secrets — must live in exactly one file. Group- and repo-scoped secrets can be spread across files as usual, because groups and repos merge across files.
This also fixes a v6 bug: a root-level secrets: block in a split config folder was silently dropped during the merge, so xfg secrets sync reported no secrets at all. Under settings: it merges correctly.
GitHub Action¶
Update your workflow files from @v6 to @v7:
Before (v6):
After (v7):
No Changes Required¶
xfg secrets sync— still a separate command; a plainxfg syncnever touches secrets, even though they now live undersettings:- Secret encryption and env-var resolution — unchanged (libsodium sealed box, values read from environment variables at runtime)
- Secret naming rules — unchanged, including case-insensitive matching
- CLI flags —
--dry-run,--no-delete,--config,--work-dir,--retriesall work the same way - Everything else under
settings:— rulesets, labels, repo settings, code scanning are unchanged