https://github.com/calebsargeant/semantic-release
GitHub Marketplace action for semantic release management with built-in Docker image promotion.
https://github.com/calebsargeant/semantic-release
github-package-deployment release-management semantic-release semantic-version
Last synced: 11 days ago
JSON representation
GitHub Marketplace action for semantic release management with built-in Docker image promotion.
- Host: GitHub
- URL: https://github.com/calebsargeant/semantic-release
- Owner: CalebSargeant
- License: mit
- Created: 2026-05-02T16:20:58.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-05-03T17:22:12.000Z (19 days ago)
- Last Synced: 2026-05-03T18:38:23.313Z (19 days ago)
- Topics: github-package-deployment, release-management, semantic-release, semantic-version
- Language: TypeScript
- Homepage: https://semver.calebsargeant.com/
- Size: 324 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Release Runner
[](https://github.com/calebsargeant/semantic-release/actions/workflows/ci.yaml)
[](https://github.com/calebsargeant/semantic-release/actions/workflows/release.yaml)
[](https://semver.calebsargeant.com)
[](https://github.com/marketplace/actions/release-runner)
[](https://github.com/calebsargeant/semantic-release/blob/main/LICENSE)
Release Runner is the GitHub Marketplace Action published as
`calebsargeant/semantic-release@v1`.
Use it when a repository should create semantic version releases from GitHub
Actions. It can create Git tags and GitHub Releases, and it can optionally build
or promote GHCR Docker images with the same release tag.
Full setup docs: [semver.calebsargeant.com](https://semver.calebsargeant.com)
## What You Need
### 1. Install the Release Runner GitHub App
If you use the default `public-app` auth mode (recommended):
- Install the [Release Runner GitHub App](https://github.com/apps/release-runner/installations/new)
on the repository or organization before your first release run.
- Alternatively, you can use a
[private GitHub App or the built-in workflow token](https://semver.calebsargeant.com/concepts/#release-write-token).
### 2. Bypass Branch Rulesets
If branch rulesets or branch protection rules guard your release branches,
allow the Release Runner app to bypass:
- Tag creation and pushes
- Release commits (when the versioning tool updates files)
- Promotion branches (`promote//`)
- Opening promotion pull requests
Without this, the app cannot push tags or version bumps.
See the full [branch protection checklist](https://semver.calebsargeant.com/organization-setup/#branch-protection-checklist).
### 3. Choose a Release Tool
Add one supported release-tool config to your repository:
| Tool | Input | Config file |
|---|---|---|
| python-semantic-release | `semantic-release-python` | `pyproject.toml` |
| semantic-release for Node.js | `semantic-release-npm` | `.releaserc.json` or `package.json` |
| GitVersion | `gitversion` | `GitVersion.yml` |
| release-please | `release-please` | `release-please-config.json` |
- semantic-release and release-please use
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) —
`fix` → patch, `feat` → minor, breaking changes → major.
- GitVersion follows your `GitVersion.yml`.
## Production Release
This creates stable releases from `main`, for example `v1.0.0`.
Before running it with the default auth mode:
- Complete the [setup steps above](#what-you-need).
- Give the release job `id-token: write`.
```yaml
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: calebsargeant/semantic-release@v1
id: release
with:
mode: release
environment: prod
environments: '["prod"]'
prerelease-identifiers: '{}'
```
By default, release jobs use the Release Runner GitHub App.
[Other auth modes](https://semver.calebsargeant.com/concepts/#release-write-token)
are also supported.
### Built-In Concurrency Lock
Use the bundled reusable workflow instead of calling the action directly
to get a workflow-level `concurrency:` group with no extra config —
two simultaneous runs on the same branch will queue rather than race
each other to the tag:
```yaml
jobs:
release:
uses: calebsargeant/semantic-release/.github/workflows/release-runner.yaml@v1
permissions:
contents: read
id-token: write
with:
mode: release
environment: prod
environments: '["prod"]'
prerelease-identifiers: '{}'
```
Same inputs as the action. See
[Concepts → Concurrency Safety](https://semver.calebsargeant.com/concepts/#concurrency-safety)
for what's protected.
## Docker Image Releases
Set `image_name` to build PR images in CI mode and promote or rebuild them
with the release tag in release mode:
- Your repository needs a [Docker Bake file](https://semver.calebsargeant.com/repository-setup/#2-choose-docker-or-version-only)
that declares the `REGISTRY`, `IMAGE_NAME`, `VERSION`, and `PLATFORMS` variables.
- CI mode builds `pr-` images from pull requests.
- Release mode promotes or rebuilds the image with the release tag.
## Environment Releases
Release Runner supports multiple environments with
[two release models](https://semver.calebsargeant.com/choose-your-setup/):
- **Trunk-Based Development** — one branch creates release tags for one or
more environments.
- **Branch-Based Development** — long-lived branches map to environments.
For example, `["dev", "staging", "prod"]` creates prerelease tags for `dev`
and `staging`, then stable tags for `prod`.
## Outputs
| Output | Meaning |
|---|---|
| `version` | Semver without prefix, for example `1.0.0` |
| `tag` | Full Git tag, for example `v1.0.0` |
| `released` | `true` when a new release was created |
| `is-prerelease` | `true` for prerelease environments |
| `resolved-environment` | Environment selected for the run |
For the complete input/output reference, see the
[action reference](https://semver.calebsargeant.com/reference/action-inputs-outputs/).
## Sponsor
If Release Runner saves you time or helps your team ship more reliably,
consider supporting its development:
[](https://github.com/sponsors/CalebSargeant)
[](https://ko-fi.com/calebsargeant)