configuration-loading.md

Configuration Loading

When specifying your config-name: inside the action's inputs, you can leverage a variety of syntax combinations to fetch your config file(s).

• Configuration Loading
  • The syntax
  • Recipes
    • Target a different folder
    • Load your config from another repo
    • Load a file on the runner's file-system (dynamic config)
    • Extend other config files using _extends
    • Merge strategies for _extends
    • Org-wide config via the .github repo
  • Edge-cases
    • Load config from your default branch
    • Fetching from a repo named github
    • Avoid changing schemes during _extends: import chain

The syntax

The full syntax can be represented as follows :

• either [github:][[owner/]repo]:filepath[@ref]
• or file:filepath

... discriminated by the scheme : file or github (the default).

^{Grammar diagram - generated by RR - Railroad Diagram Generator}

Everything besides the filepath is optional. This path is interpreted such as you can easily navigate your repo's files :

• relative filepaths are resolved your repo's .github folder
• absolute filepaths are resolved at your repo's root folder

When using the github: scheme, you'll be able to specify a different repo and/or ref to fetch the config at. If you do not specify any/some of them, they'll be inferred using the runner's context. See Variables reference and @actions/github's context for more.

The file: schemes requires the runtime's file-system (the runner's) to have the file at hand. If the desired file is in your repo, make sure to use actions/checkout.

Note

If you want to use an unmodified copy of the config that was pushed to your repo on the same event your workflow is running for, you need neither the file: scheme nor the actions/checkout action.

Simply use the default github: scheme :

uses: step-security/release-drafter@v7
with:
  config-name: relative/path/to/my/config.yaml

... release-drafter will automatically fetch your file from your working/current branch using octokit.

Recipes

Target a different folder

• config-name: release-drafter.yaml
  • resolves .github/release-drafter.yaml using the contents Github API endpoint
• config-name: /configs/release-drafter.yaml
  • resolves configs/release-drafter.yaml using the contents Github API endpoint
• config-name: file:../src/common/release-drafter.yaml
  • resolves /home/runner/workspace/src/common/release-drafter.yaml using node:fs

Load your config from another repo

• config-name: .github:release-drafter.yaml@v2
  • resolves .github/release-drafter.yaml inside your .github repo at tag v2
• config-name: my_configs:release-drafter.yaml
  • resolves .github/release-drafter.yaml inside your my_configs repo on the default branch
• config-name: torvalds/dotfiles:/ci/release-drafter.yml@v6.19-rc8
  • resolves Linus's release-drafter config

Load a file on the runner's file-system (dynamic config)

# .github/release-drafter-template.yml
template: |
  $CHANGES

  **Full Changelog**: generated by {{CURR_REF}}

# .github/workflows/release.yml
jobs:
  release-drafter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Generate dynamic config from template using 'sed'
        run: sed "s|{{CURR_REF}}|${{ github.ref }}|g"
          .github/release-drafter-template.yml >
          .github/release-drafter-parsed.yml
      - name: Use dynamic release-drafter configuration
        uses: step-security/release-drafter@v7
        with:
          config-name: file:release-drafter-parsed.yml

Extend other config files using _extends

# configs/release-drafter-common.yml
template: |
  ## What’s Changed

  $CHANGES

# .github/release-drafter/backend.yml
_extends: /configs/release-drafter-common.yml
tag-template: "backend/v$RESOLVED_VERSION"

steps:
  - uses: step-security/release-drafter@v7
    with:
      config-name: release-drafter/backend.yml

Imported config will be :

tag-template: "backend/v$RESOLVED_VERSION"
template: |
  ## What’s Changed

  $CHANGES

Note

The same syntax as config_name: applies to _extends (and to the from key of its mapping form below). Below all produce the same output :

• _extends: ../configs/release-drafter-common.yml
• _extends: github:/configs/release-drafter-common.yml
• _extends: github:../configs/release-drafter-common.yml
• _extends: file:../configs/release-drafter-common.yml
  • make sure to actions/checkout@v6 the repo beforehand

Merge strategies for _extends

Configs in an _extends chain are merged shallowly: a key in the extending file replaces the inherited value entirely. That is usually what you want, but for list keys (categories, autolabeler, replacers, ...) it means an extending file cannot add entries without repeating the whole inherited list.

The mapping form of _extends lets the extending file pick a merge strategy per key: from is the target (same syntax as the string form), strategy maps config keys to how they merge:

# your-org/.github: .github/release-drafter.yml
categories:
  - title: "🚀 Features"
    when:
      label: "feature"

# your-repo: .github/release-drafter.yml
_extends:
  from: your-org/.github
  strategy:
    categories: append
categories:
  - type: "pre-exclude"
    when:
      label: "skip-changelog"

Imported config will be :

categories:
  - title: "🚀 Features"
    when:
      label: "feature"
  - type: "pre-exclude"
    when:
      label: "skip-changelog"

Semantics :

• Available strategies are override (the default for every key, identical to the shallow merge above), append (the inherited list plus the extending file's entries, in that order), and prepend (the extending file's entries first). Categories are evaluated in the order they are defined, so the strategy decides where the file's own entries land.
• append and prepend only work on list values. Merging a key whose own or inherited value is present and not a list fails with an error naming the key and the file. An absent or empty (categories:) value counts as an empty list.
• A file's strategy governs only the step where that file itself is merged onto the configs it extends; it is not inherited. In a chain A extends B extends C, B's strategy applies when B is merged onto C, and A's strategy applies when A is merged onto that result. A file without a strategy overrides, even if a file below it appended.
• Like the string form, the _extends key is stripped from the composed configuration and never reaches the config schema.

Warning

Older release-drafter versions only understand the plain string form of _extends and fail on the mapping form. Make sure every repository using it runs an action version that supports it.

Org-wide config via the .github repo

If release-drafter cannot find the config file in the current repository, it will automatically look for it in your organisation's .github repository.

This means you can keep a single shared config in <your-org>/.github and all repositories in your organisation will pick it up without any per-repo configuration:

# <your-org>/.github/.github/release-drafter.yml
template: |
  ## What's Changed

  $CHANGES

Note

The fallback only applies when:

• the config-name: does not explicitly target another repository, and
• release-drafter is not already running inside the .github repository itself (to avoid an infinite loop).

Edge-cases

Load config from your default branch

When not specifying a ref (with @ref), octokit will fetch from the default branch of the repo.

However, our implementation of the config-loading will automatically set a value for this ref parameter whenever the target repo and repo owner are the same release-drafter is running for.

For instance, if you are running :

# github.com/john_doe/my_repo/.github/workflows/release.yaml
on:
  push:
    branches:
      - feature/implement-auth

jobs:
  release-drafter:
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/release-drafter@v7
        with:
          config-name: release-drafter.yaml

... This will fetch https://github.com/john_doe/my_repo/.github/workflows/release.yaml?ref=feature/implement-auth.

If you need to fetch to your default branch instead, you will need to know the name of your default branch :

config-name: release-drafter.yaml@main

... or get it from your workflow's context :

config-name: release-drafter.yaml@${{ github.event.repository.default_branch }}

Fetching from a repo named github

The github: prefix is used internally to recognize you want to explicitly fetch from a remote (using octokit) instead of loading a file on the runtime's filesystem.

The same prefix could also be used if you wanted to specify fetching from a repo you own named github.

For instance, github:release-drafter.yaml would mean both :

• fetch from current repo at current ref
• and fetch from my repo named github

If you intent the later, you will need to be more explicit. Use either :

• my_org_or_name/github:release-drafter.yaml
• or github:github:release-drafter.yaml
• or even github:my_org_or_name/github:release-drafter.yaml

Avoid changing schemes during _extends: import chain

When configs extend each-other, release-drafter will need to walk the import-chain using the scheme that whas specified in every file.

Using the file: scheme with _extends is supported, but you need to make sure all files are on the system and on the correct path.

If you start extending configs using the github: (default, recommended) scheme, you cannot switch to file: mid-flight.