Docouture

Releasing a documentation

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 (main on a trunk-based site — see Branching model for a git-flow one) carrying the docs/release label. 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:

  1. Edit docs/.release-version to the target version (e.g. 1.0.0)

  2. Open a PR with that change, labelled docs/release

  3. 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

descriptor (default)

docs/.release-version, committed by the release pull request. The forward-bump and the git-flow sync described here apply only to this source.

github-release

The tag of the published GitHub Release, minus the optional docouture.versionSourcePrefix (for example my-lib@). The docs follow the code release. A merged docs-only docs/release pull request republishes the docs at the highest published stable Release (see Republishing docs under github-release).

tag-bump

The highest existing docs/v* tag plus a bump: docs/release bumps patch, docs/release-minor minor and docs/release-major major (the highest wins when several are present). The first release has no tag to bump from, so run docouture-release manually with an explicit version.

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: descriptor reads the file (no dependency install), github-release shows the version a docs-only pull request would republish (or says the docs follow the code release when the pull request also carries release-type/), and tag-bump shows 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. Use workflow_dispatch with an explicit version for a minor or major bump in that case.

  • The workflows run the CLI your project installed. Update @inditextech/docouture-cli and install it first, then run docouture upgrade (which writes "versionSource": "descriptor" on a site that lacks it, with no behavior change), then optionally docouture version-source. docouture doctor shows the active source and warns about a stray or missing docs/.release-version and about a project CLI that predates release resolve.

Republishing docs under github-release

A pull request carries no version under github-release, so a merged docs-only pull request labelled docs/release takes it from the repository’s published GitHub Releases instead: the highest SemVer version among them, not the newest one (a backport released after 1.4.0 does not make the docs go back to 1.3.9). The workflow lists the non-draft, non-prerelease Releases and docouture release resolve then:

  • keeps only tags that start with docouture.versionSourcePrefix (with no prefix set, every tag is tried as a version as it is), so a repository that publishes several packages picks the right one;

  • strips the prefix and ignores anything that is not SemVer, or is a SemVer prerelease such as 1.5.0-rc.1;

  • republishes docs/v<highest>. The tag is force-recreated like any republish, and there is no descriptor bump or git-flow sync.

The prefix applies to the Release tags the version is read from, never to the docs/v* tags this workflow creates. Docs tags are the output (docs/v1.4.1); Release tags are the input (1.4.1, or my-lib@1.4.1 when a repository releases several packages and prefixes each package’s tag).

  • No prefix (the default): only plain SemVer Release tags such as 1.4.1 are considered. Prefixed tags like my-lib@1.4.1 are not valid SemVer, so they are ignored.

  • With a prefix, such as my-lib@: only that package’s Releases are considered, and the prefix is stripped before ordering.

For example, the docouture repository publishes plain Releases (1.4.0, 1.3.2, …​) and sets no prefix, so a docs-only docs/release PR republishes docs/v1.4.0.

If no Release matches, the merge fails with a message naming the prefix and how many releases were considered; the preview comment warns about it first.

Which trigger releases what

What a merged pull request, or a manual run, releases under each version source. "Code release" means the pull request carries a release-type/* label (without skip-release) and the code release publishes a GitHub Release; see Combined code and docs releases.

Scenario github-release tag-bump descriptor (default)

Pull request with code and docs (release-type/*, with or without docs/release)

Not released on merge. When the code release publishes a Release, the docs are released at that Release’s tag.

Not released on merge. When the code release publishes a Release, the docs are released at the latest docs/v* tag plus a patch bump (a Release event carries no labels).

Not released on merge. When the code release publishes a Release, the docs are released at the version in docs/.release-version.

Pull request with only docs (docs/release, no release-type/*)

Released on merge, republishing the highest published stable Release (no new version; see Republishing docs under github-release). Fails if no Release qualifies.

Released on merge at the latest docs/v* tag plus the bump the label selects: docs/release patch, docs/release-minor minor, docs/release-major major.

Released on merge at the version in docs/.release-version, which the pull request commits; the file is then bumped forward.

Manual run (workflow_dispatch)

Released at the version typed in the form.

Released at the version typed in the form. The only way to cut the first release, or a bump other than patch after a Release event.

Released at the version typed in the form; docs/.release-version is not bumped for a republish.

In every case the tag is force-recreated if it already exists, and only descriptor runs the descriptor bump and the git-flow sync.

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/release PR, but the docs are still published — publish doesn’t wait on its result.

  • The GitHub App that docouture-release.yml already uses needs pull-requests: write (and workflows: write, since the release branch can carry workflow-file changes) in addition to contents: write. Existing git-flow sites run docouture upgrade once to get the new job and the package.json field.

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 the docs/release label is not needed.

  • docs/release together with release-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. The docs/release label is redundant.

  • skip-release is not the answer. In the code release convention it cancels the code release. The docs workflow treats a pull request with skip-release as if it had no release-type/* label, so docs/release releases 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.

Recovering

Run the workflow by hand: Actions tab → "docouture-release" → Run workflow, supplying the version in versioned mode. Or release the docs in a separate pull request labelled docs/release without release-type/*.

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.