GitHub Environments¶
xfg can create, update and (opt-in) delete GitHub deployment environments: the environment itself, which branches and tags can deploy to it, and its secrets.
GitHub only
Environments only apply to GitHub repos. Azure DevOps and GitLab repos are skipped. Environments on private repos need a paid GitHub plan (Pro, Team or Enterprise); on a free plan, private repos are skipped with a warning.
Quick Start¶
id: my-config
settings:
environments:
release:
deploymentBranchPolicy:
custom:
- type: branch
name: main
- type: tag
name: "v*.*.*"
secrets:
NPM_TOKEN:
env: NPM_TOKEN_VALUE
repos:
- git: git@github.com:your-org/your-repo.git
# Preview changes (dry-run)
xfg sync -c config.yaml --dry-run
# Create the environments and their branch policies
xfg sync -c config.yaml
# Write the environment secrets
xfg secrets sync -c config.yaml
xfg sync creates and updates environments and branch policies but never touches secrets, so it never needs secret values. Only xfg secrets sync writes environment secrets. Run xfg sync first: secrets can't be written to an environment that doesn't exist yet.
A workflow that xfg sync pushes in the same run that creates its environment can start before xfg secrets sync writes the secrets. It fails until you re-run it after xfg secrets sync has written the secrets.
Deployment Branch Policy¶
deploymentBranchPolicy controls which refs can deploy to the environment. Use one of these:
| Config | Who can deploy |
|---|---|
| (omitted) | Any branch |
protectedBranches: true |
Only branches with branch protection rules |
custom: [{ type, name }, ...] |
Only branches or tags matching the listed patterns |
settings:
environments:
preview: {} # any branch
staging:
deploymentBranchPolicy:
protectedBranches: true
production:
deploymentBranchPolicy:
custom:
- type: branch
name: main
- type: branch
name: "release/*"
- type: tag
name: "v*"
Patterns use fnmatch syntax. type is branch or tag.
xfg adds missing patterns. Patterns already on GitHub that are not in your config are left in place and reported as a warning:
Set deleteOrphaned: true on a custom policy to delete those patterns instead (see Deleting Orphans).
Environment Secrets¶
Environment secrets use the same config as repo secrets: each entry names the environment variable that holds the value.
- Values are encrypted with the environment's own public key and never shown in output.
- Existing secrets always show as
update, because GitHub never returns secret values. - Secrets not in config are left alone unless the environment's
secretsmap setsdeleteOrphaned: true(see Deleting Orphans).inheritis not supported here. - If an environment doesn't exist yet,
xfg secrets sync --dry-runstill plans its secrets. A real run fails before writing anything on a public repo; on a private repo it skips that environment's secrets with a warning.
Inheritance¶
Environments merge by name (ignoring case) through root, groups, conditional groups, and the repo:
- A
deploymentBranchPolicyset at a lower layer merges field by field with the inherited one. To switch betweenprotectedBranchesandcustom, setinherit: falseon the layer that changes it. deploymentBranchPolicy: falseclears an inherited policy, so any branch can deploy. Not allowed at root.- Secrets merge by name. Set a secret to
falseto drop an inherited one. - Set an environment to
falseto drop it.inherit: falsein theenvironmentsmap drops every inherited environment. Inside one environment,inherit: falsedrops only that environment's inherited fields, so restate everything it needs.inheritis not allowed at root.
id: environments
settings:
environments:
release:
deploymentBranchPolicy:
protectedBranches: true
secrets:
NPM_TOKEN: { env: NPM_TOKEN_VALUE }
repos:
- git: git@github.com:your-org/app.git
settings:
environments:
release:
deploymentBranchPolicy:
inherit: false # drop protectedBranches
custom:
- { type: tag, name: "v*" }
secrets:
NPM_TOKEN: false # drop the inherited secret
- git: git@github.com:your-org/docs.git
settings:
environments:
release: false # no release environment here
A plain custom list replaces the inherited patterns. To add to them, use $arrayMerge: append:
id: environments
settings:
environments:
release:
deploymentBranchPolicy:
custom:
- { type: branch, name: main }
repos:
- git: git@github.com:your-org/app.git
settings:
environments:
release:
deploymentBranchPolicy:
custom:
$arrayMerge: append
$values:
- { type: tag, name: "v*" } # main and v*
custom does not take merge
A pattern is identified by its type and name together, and no single $matchBy key covers both, so xfg rejects $arrayMerge: merge on custom. Use append, prepend or replace.
By default xfg never deletes anything: removing an environment, pattern or secret from the config leaves it on GitHub. Deleting Orphans covers the opt-in.
Deleting Orphans¶
deleteOrphaned is off by default and can be turned on at three levels:
| Key | Deletes | Run by |
|---|---|---|
environments.deleteOrphaned |
Environments on GitHub not in the merged config | xfg sync |
environments.<name>.deploymentBranchPolicy.deleteOrphaned |
Branch and tag patterns not in custom |
xfg sync |
environments.<name>.secrets.deleteOrphaned |
Secrets in that environment not in its secrets map |
xfg secrets sync |
settings:
environments:
deleteOrphaned: true # delete environments not listed here
release:
deploymentBranchPolicy:
deleteOrphaned: true # delete patterns not listed in custom
custom:
- type: tag
name: "v*.*.*"
secrets:
deleteOrphaned: true # delete release secrets not listed here
NPM_TOKEN:
env: NPM_TOKEN_VALUE
Deleting an environment deletes its secrets and protection rules
environments.deleteOrphaned deletes every environment on the repo that is not in your config, including ones created by hand or by other tools, along with their secrets, variables and protection rules. A map that holds only deleteOrphaned: true deletes all of them. Run --dry-run first.
How each key merges:
environments.deleteOrphanedandsecrets.deleteOrphanedresolve innermost-wins, like repo secrets.inherit: falsedrops the inherited environments and an inheriteddeleteOrphaned. A layer that wants cleanup setsdeleteOrphaned: trueitself, and then deletes the inherited environments.deploymentBranchPolicy.deleteOrphanedis a field of the policy and inherits like the others. It works on the mergedcustomlist, so a repo that replacescustomwith a plain list deletes the inherited patterns on GitHub. To keep them, add with$arrayMerge: append. It is only valid withcustom.- A secrets map that holds only
deleteOrphaned: truedeletes every secret in that environment.
Safety:
--no-deleteturns off every deletion for the run, whatever the config says.--dry-runshows deletions as-lines, in the terminal and the job summary, without deleting anything.- When an environment switches to
custom, xfg can't tell which patterns it already has until the next run, so pattern deletions show up then. - Deleting environments and patterns needs Administration: Read and write. Without it the run fails with a message naming that permission.
Dry Run Output¶
your-org/your-repo - Environments:
+ environment "release"
deployment branches: custom
+ branch "main"
+ tag "v*.*.*"
~ environment "staging"
deployment branches: all → protected
~ environment "production"
- branch "hotfix/*"
- environment "preview"
Plan: 4 environments (1 to create, 2 to update, 1 to delete)
xfg secrets sync --dry-run lists environment secrets next to repo secrets:
[1/1] ✓ your-org/your-repo: Secrets: [DRY RUN] 1 created, 1 updated, 1 deleted
+ secret "NPM_TOKEN" (environment "release")
~ secret "SIGNING_KEY" (environment "release", update, value write-only)
- secret "OLD_TOKEN" (environment "release")
Plan: 3 secrets (1 to create, 1 to update, 1 to delete)
Permissions¶
- Creating, updating and deleting environments and branch policies: Administration: Read and write.
- Listing environments and branch policies: Actions: Read.
xfg secrets synclists environments too. - Environment secrets: Environments: Read and write.
See GitHub App.
GitHub API Reference¶
Environments are managed via the GitHub Deployment Environments API, Deployment Branch Policies API and Actions Secrets API:
GET /repos/{owner}/{repo}/environments— List environmentsPUT /repos/{owner}/{repo}/environments/{name}— Create or update an environment's branch policyDELETE /repos/{owner}/{repo}/environments/{name}— Delete an environment (deleteOrphaned)GET /repos/{owner}/{repo}/environments/{name}/deployment-branch-policies— List branch and tag patternsPOST /repos/{owner}/{repo}/environments/{name}/deployment-branch-policies— Add a patternDELETE /repos/{owner}/{repo}/environments/{name}/deployment-branch-policies/{id}— Delete a pattern (deleteOrphaned)GET /repos/{owner}/{repo}/environments/{name}/secrets— List environment secrets (names only)GET /repos/{owner}/{repo}/environments/{name}/secrets/public-key— Get the environment's encryption keyPUT /repos/{owner}/{repo}/environments/{name}/secrets/{secret_name}— Create or update an environment secretDELETE /repos/{owner}/{repo}/environments/{name}/secrets/{secret_name}— Delete an environment secret (deleteOrphaned)