A release is cut by running .github/workflows/docouture-release.yml (scaffolded by
docouture new), not by hand-editing anything under docs/. Two triggers actually do
anything on a fresh site:
-
Manually — Actions tab → "docouture-release" → Run workflow. Works immediately.
-
Automatically — merge a pull request into the release branch (
mainon a trunk-based site — see Branching model for a git-flow one) carrying thedocs/releaselabel. That label isn’t created automatically — see Prerequisites — so until it exists, only the manual trigger works; a merge without it is a silent no-op, not an error.
A third trigger — a published GitHub Release — is scaffolded alongside these but stays
dormant on a fresh site: it only fires once the repo separately labels PRs
release-type/*/skip-release and publishes its own Releases, a convention this
scaffolding doesn’t set up. It exists so that, if a repo’s own code releases and docs
releases can land in the same merged PR, the docs release waits for the code release to
actually publish instead of firing twice for one merge — adopting that convention later
is then a label/workflow change elsewhere, not a rewrite of this file. See
Combined code and docs releases for how the two interact.
Under the hood: docouture version <value> patches docs/src/antora.yml on a one-off
commit built on the release branch’s current tip, git tag docs/v<value> is created
there, and the tag is pushed — the release branch itself is never advanced.
Before any of that: the resolved version (docs/.release-version, or the
workflow_dispatch version input, in versioned mode; see Where the version comes from for the
other sources) is validated against full SemVer 2.0.0 — a leading v, a bare 1.2,
or any other malformed value fails the workflow immediately with a clear error, instead
of tagging first and only failing later inside the version-bump step.
docouture-release-preview.yml runs the same check earlier, as a PR comment, before the
merge that would have triggered it.
It runs only on pull requests opened from a branch of the repository itself: a fork’s
pull request gets a read-only token that cannot post the comment, so the preview is
skipped there.
Standalone mode
Every release retargets the same docs/stable tag — force-moved, not appended to. Nothing
to set beforehand; the workflow’s default input is fine.
Versioned mode
The target version comes from docs/.release-version, not a form field, when
triggered by a labelled PR merge:
-
Edit
docs/.release-versionto the target version (e.g.1.0.0) -
Open a PR with that change, labelled
docs/release -
Merge it — the workflow tags
docs/v1.0.0, then bumps the file forward to the next patch version so it’s always ready for whatever comes next
(Or skip the PR: run the workflow manually via workflow_dispatch and type the
version directly — its form field is what a versioned-mode release actually requires
there, unlike standalone’s, where the default is fine.)
Where the version comes from
By default the version comes from docs/.release-version, as above. That file duplicates
the docs/v* tags, and it needs the post-release bump push (and, under git-flow, the sync
pull request below). A versioned site can instead choose another source with
docouture.versionSource in docs/package.json:
| Source | The version comes from |
|---|---|
|
|
|
The tag of the published GitHub Release, minus the optional |
|
The highest existing |
Change the source with docouture version-source <source> (see CLI);
docouture new --mode versioned asks for it. Switching to github-release or tag-bump
removes docs/.release-version; for tag-bump it also prints the gh label create
commands for the two extra labels, which you create once. docouture release resolve
implements the rules for both workflows.
-
The preview comment follows the source:
descriptorreads the file (no dependency install),github-releasesays the docs follow the code release without naming a version, andtag-bumpshows the version released if the pull request merged now, which can change if another release lands first. -
Under
tag-bump, a run started by a published GitHub Release has no pull request labels to read, so it bumps patch. Useworkflow_dispatchwith an explicit version for a minor or major bump in that case. -
The workflows run the CLI your project installed. Update
@inditextech/docouture-cliand install it first, then rundocouture upgrade(which writes"versionSource": "descriptor"on a site that lacks it, with no behavior change), then optionallydocouture version-source.docouture doctorshows the active source and warns about a stray or missingdocs/.release-versionand about a project CLI that predatesrelease resolve.
Under git-flow: the sync pull request
This applies to the descriptor source only; the other sources have no bump to carry over
and skip the job.
The forward-bump is committed on the release branch only. On a git-flow site the
workflow’s sync-prerelease job then opens a pull request from
automated/sync-docs-release-<version>-to-<prerelease> into the prerelease branch, so
docs/.release-version (and anything else the release branch gained) reaches it —
merge that PR. The prerelease branch name comes from docs/package.json’s
`docouture.prereleaseBranch; if it is missing the release fails before tagging, with a
message pointing at docouture upgrade, which adds it.
-
The job is skipped on trunk-based sites, on a republish, when the prerelease branch already contains the release branch, and when that branch doesn’t exist.
-
A failure there turns the run red and comments on the merged
docs/releasePR, but the docs are still published —publishdoesn’t wait on its result. -
The GitHub App that
docouture-release.ymlalready uses needspull-requests: write(andworkflows: write, since the release branch can carry workflow-file changes) in addition tocontents: write. Existing git-flow sites rundocouture upgradeonce to get the new job and thepackage.jsonfield.
docouture version vs. a real release
docouture version <value> is the narrower tool the workflow itself calls internally
— it only rewrites docs/src/antora.yml’s `version:/prerelease: fields in place.
Useful for local, throwaway testing of how a version renders; it does not cut a
release on either mode, and never touches docs/.release-version:
$ docouture version 1.0.0
$ docouture version 1.1.0-rc.0 --prerelease
Every release tag is force-recreated
Republishing an already-released version (fixing a docs typo caught after the tag
went out) is a deliberate, ordinary act — no separate flag needed. The one
difference: the docs/.release-version forward-bump step is skipped on a republish,
since that file’s current value was typically already the next planned target.
Combined code and docs releases
If your repository also cuts code releases, labelling the merged pull request
release-type/* and publishing a GitHub Release, the docs can be released together with
the code. The docouture-release.yml workflow reacts to that Release being published, not to
the merge itself:
-
release-type/alone* is enough. When the code release publishes a (non-pre-release) GitHub Release, the docs are released as part of it, so thedocs/releaselabel is not needed. -
docs/releasetogether withrelease-type/* does not release the docs on merge. The merge-time path backs off, to avoid releasing the docs twice for one merge, and the docs are released when the Release is published. Thedocs/releaselabel is redundant. -
skip-releaseis not the answer. In the code release convention it cancels the code release. The docs workflow treats a pull request withskip-releaseas if it had norelease-type/*label, sodocs/releasereleases the docs on merge again.
docouture-release-preview.yml comments on the pull request with what will really happen
for these label combinations. It stays silent on a code-only pull request that does not
change docs/.
When the docs are not released
The docs release depends on the code release publishing a Release. They are not released when:
-
the code release fails before publishing a Release, or leaves it as a draft;
-
the Release is marked as a pre-release: a published pre-release never moves the stable docs tag;
-
your code release does not publish a GitHub Release at all.
In versioned mode under the descriptor source there is one more case. If
docs/.release-version is missing or invalid, the docs release fails when the Release is published, after the code release has
already gone out. The preview flags this on a pull request with docs/release; with
release-type/* alone it does not check the file, which is normally present because every
release bumps it forward.
Protected release branches
If the release branch is covered by a ruleset that requires pull requests, add the GitHub
App behind APP_CLIENT_ID and APP_PRIVATE_KEY to the ruleset’s bypass list. The release
job pushes the release tag and the docs/.release-version bump with that App’s token.
That token is deliberately not narrowed with owner, repositories or permission-*
inputs in the release job. A narrowed installation token loses the App’s ruleset bypass:
the bump is rejected with GH013 Changes must be made through a pull request and
docs/.release-version stays on the released version. The tradeoff is that the release
job’s token carries all of the App’s installation permissions, so install the App only
where it is needed. The sync-prerelease and publish jobs never push to the release
branch, so they keep narrowed tokens.