@at-blacknight/semantic-release-ci-output

semantic-release plugin that outputs release information to CI platforms. Auto-detects the CI environment and writes variables using the native mechanism for each platform.

Works in dry-run mode — unlike @semantic-release/changelog, the changelog file is written during generateNotes which executes in dry-run.

Supported Platforms

| Platform | Output Mechanism | |----------|-----------------| | GitHub Actions | Writes to $GITHUB_OUTPUT file | | Azure DevOps | ##vso[task.setvariable] commands | | GitLab CI/CD | Writes to dotenv file | | Other/Local | Logs key=value to stdout |

Platform detection is powered by env-ci.

Install

npm install --save-dev @at-blacknight/semantic-release-ci-output

Usage

Add the plugin to your plugins list in your semantic-release configuration. It replaces both @semantic-release/changelog and @semantic-release/exec for CI variable output.

# .releaserc.yaml
plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - "@at-blacknight/semantic-release-ci-output"

With options

plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - - "@at-blacknight/semantic-release-ci-output"
    - writeNotesFile: true
      notesFilePath: "CHANGELOG-NEW.md"
      notesFileBehaviour: "overwrite"
      setWouldRelease: true
      setLastReleaseVariables: false
      isOutput: true

Output Variables

The following variables are set on the CI platform:

Always set (analyzeCommits)

| Variable | Description | |----------|-------------| | would_release | false initially, set to true if a release is determined |

Set when a release is determined (verifyRelease)

| Variable | Description | |----------|-------------| | would_release | true | | version | The next release version (e.g. 1.2.3) | | release_type | The release type (major, minor, patch, prerelease) | | release_channel | The release channel (e.g. uat, develop, or empty for default) | | git_tag | The git tag for the release (e.g. v1.2.3) | | git_head | The git commit SHA |

Last release variables (opt-in)

When setLastReleaseVariables: true:

| Variable | Description | |----------|-------------| | last_release_version | Previous release version | | last_release_git_head | Previous release commit SHA | | last_release_git_tag | Previous release git tag | | last_release_channel | Previous release channel |

Changelog File

By default, the plugin writes the release notes to CHANGELOG-NEW.md in the working directory. This happens during generateNotes which runs even in --dry-run mode.

| Option | Default | Description | |--------|---------|-------------| | writeNotesFile | true | Write release notes to a file | | notesFilePath | CHANGELOG-NEW.md | Path to the changelog file | | notesFileBehaviour | overwrite | overwrite, prepend, or append |

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | setWouldRelease | true | Set the would_release variable | | setLastReleaseVariables | false | Set variables for the last release | | isOutput | true | Mark variables as output variables (ADO: isOutput=true) | | writeNotesFile | true | Write changelog file | | notesFilePath | CHANGELOG-NEW.md | Changelog file path | | notesFileBehaviour | overwrite | How to handle existing changelog file |

Lifecycle Hooks

| Hook | Purpose | |------|---------| | analyzeCommits | Sets would_release=false and last release variables | | verifyRelease | Sets would_release=true and all release variables | | generateNotes | Writes the changelog file |

License

MIT