Skip to content

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:

⚠ your-org/your-repo: environment "production" has branch "hotfix/*" not in config - left in place

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.

settings:
  environments:
    release:
      secrets:
        NPM_TOKEN:
          env: NPM_TOKEN_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 secrets map sets deleteOrphaned: true (see Deleting Orphans). inherit is not supported here.
  • If an environment doesn't exist yet, xfg secrets sync --dry-run still 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 deploymentBranchPolicy set at a lower layer merges field by field with the inherited one. To switch between protectedBranches and custom, set inherit: false on the layer that changes it.
  • deploymentBranchPolicy: false clears an inherited policy, so any branch can deploy. Not allowed at root.
  • Secrets merge by name. Set a secret to false to drop an inherited one.
  • Set an environment to false to drop it. inherit: false in the environments map drops every inherited environment. Inside one environment, inherit: false drops only that environment's inherited fields, so restate everything it needs. inherit is 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.deleteOrphaned and secrets.deleteOrphaned resolve innermost-wins, like repo secrets. inherit: false drops the inherited environments and an inherited deleteOrphaned. A layer that wants cleanup sets deleteOrphaned: true itself, and then deletes the inherited environments.
  • deploymentBranchPolicy.deleteOrphaned is a field of the policy and inherits like the others. It works on the merged custom list, so a repo that replaces custom with a plain list deletes the inherited patterns on GitHub. To keep them, add with $arrayMerge: append. It is only valid with custom.
  • A secrets map that holds only deleteOrphaned: true deletes every secret in that environment.

Safety:

  • --no-delete turns off every deletion for the run, whatever the config says.
  • --dry-run shows 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 sync lists 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 environments
  • PUT /repos/{owner}/{repo}/environments/{name} — Create or update an environment's branch policy
  • DELETE /repos/{owner}/{repo}/environments/{name} — Delete an environment (deleteOrphaned)
  • GET /repos/{owner}/{repo}/environments/{name}/deployment-branch-policies — List branch and tag patterns
  • POST /repos/{owner}/{repo}/environments/{name}/deployment-branch-policies — Add a pattern
  • DELETE /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 key
  • PUT /repos/{owner}/{repo}/environments/{name}/secrets/{secret_name} — Create or update an environment secret
  • DELETE /repos/{owner}/{repo}/environments/{name}/secrets/{secret_name} — Delete an environment secret (deleteOrphaned)