GitHub
Creates a git tag and a GitHub release for the version, and uploads matching artifacts as release assets. If a Markdown changelog is present, this target reads the release name and description from it.
Configuration
Section titled “Configuration”| Option | Description |
|---|---|
tagPrefix |
Prefix for new git tags (e.g., v). Empty by default. |
previewReleases |
Automatically detect and create preview releases. Default: true |
tagOnly |
Only create a tag (without a GitHub release). Default: false |
floatingTags |
List of floating tags to create/update. Supports {major}, {minor}, {patch} placeholders. |
The repository itself comes from the top-level github
setting or your git remote, not from this target.
Environment Variables
Section titled “Environment Variables”| Name | Description |
|---|---|
GITHUB_TOKEN |
Personal GitHub API token (create one) |
Example
Section titled “Example”targets: - name: github tagPrefix: v previewReleases: trueTag Prefixes
Section titled “Tag Prefixes”tagPrefix is prepended to every tag this target creates: tagPrefix: v
turns version 1.2.3 into tag v1.2.3.
Craft also reads the prefix from the first github target when it looks up
previous releases, so latest-tag detection, the changelog base, and CalVer
scans only see tags with that prefix. That is what lets several products share
one repository; see Monorepos & Release Workspaces.
Floating Tags
Section titled “Floating Tags”Use floatingTags to maintain “latest major version” tags that always point to the most recent release:
targets: - name: github floatingTags: - "v{major}" # Creates v2 for version 2.15.0 - "v{major}.{minor}" # Creates v2.15 for version 2.15.0This is useful for users who want to pin to a major version while automatically receiving updates.
Prereleases (versions with a prerelease identifier, such as 2.16.0-alpha.0)
do not move floating tags, so users pinned to v2 only get stable releases.
When Craft looks up the previous release, it ignores tags that have no
major.minor.patch version after the tag prefix, such as v2, v2.15, or
latest. A floating tag on the same commit as a release tag therefore does not
hide that release. Prerelease tags still count as releases: a prerelease builds
on the previous prerelease of its version, and a stable release on the latest
stable tag (see Changelog base).
Preview Releases
Section titled “Preview Releases”If previewReleases is true (default), releases containing pre-release identifiers like alpha, beta, rc, etc. are marked as pre-releases on GitHub. See Versioning for the identifiers Craft recognizes.
Release Workspaces
Section titled “Release Workspaces”Release workspaces are a Craft-wide feature, not specific to this target. See Monorepos & Release Workspaces for how to configure them.
Inside a workspace, this target prefixes the release title with the tag: a
changelog heading of 0.2.0 with tagPrefix: 'cli@' produces a release titled
cli@0.2.0, so releases of different products stay distinguishable. Outside
workspaces, the changelog heading is used as-is.
The “Latest” badge in monorepos
Section titled “The “Latest” badge in monorepos”GitHub tracks a single “Latest” release per repository, not per tag prefix. Craft decides whether to mark a release as latest by comparing its version against the repository’s current latest release (isLatestRelease), which is not prefix-scoped. In a monorepo this means the “Latest” badge can move between products (e.g. publishing cli@9.0.0 may take the badge from mcp@3.0.0, and publishing cli@1.2.3 while mcp@3.0.0 is latest won’t earn the badge). Tags, changelogs, release branches, and version detection remain correctly per-product — only GitHub’s single “Latest” pointer is shared.