From cfb91e555024621d48e36a5bd89c2c18edcf1abd Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 3 Oct 2026 18:19:27 +0300 Subject: [PATCH] docs: cover GitHub on the index page; branch-prefix reads the head commit --- docs/index.md | 48 ++++++++++++++++++++++++-------- docs/strategies/branch-prefix.md | 4 +-- 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index 34a10c7..29a7037 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,17 +7,44 @@ -Auto-tag your GitLab repository with semantic version tags from CI, -using one of two bump strategies. +Auto-tag your GitHub or GitLab repository with semantic version tags +from CI, using one of two bump strategies. From a single command in your CI pipeline, semvertag reads the head -commit and tag history from your GitLab project through the API, -decides the semver bump with the strategy you've configured, and -creates the new git tag. +commit and tag history through the GitHub or GitLab API, decides the +semver bump with the strategy you've configured, and creates the new +git tag. ## Quick start -In GitLab CI, run semvertag as a job on the default branch (see +semvertag bumps from the highest existing semver tag and never creates +the first one. Before the first run, create a plain semver tag such as +`0.1.0` (a `v` prefix does not parse and is ignored). + +### GitHub Actions + +Run the action on pushes to the default branch (see +[GitHub Actions](providers/github.md) for token options and outputs): + +```yaml +name: semvertag +on: + push: + branches: [main] + +permissions: + contents: write + +jobs: + tag: + runs-on: ubuntu-latest + steps: + - uses: modern-python/semvertag@v0 +``` + +### GitLab CI + +Run semvertag as a job on the default branch (see [GitLab CI](providers/gitlab.md) for the full snippet): ```yaml @@ -33,11 +60,7 @@ semvertag: - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' ``` -semvertag bumps from the highest existing semver tag and never creates -the first one. Before the first run, create a plain semver tag such as -`0.1.0` (a `v` prefix does not parse and is ignored). - -For local testing or one-off invocations: +For local testing or one-off invocations against GitLab: ```sh SEMVERTAG_TOKEN= \ @@ -53,7 +76,8 @@ SEMVERTAG_PROJECT_ID= \ semvertag ships with two bump-decision strategies: - [branch-prefix](strategies/branch-prefix.md), the default, bumps - based on the source branch of the latest merge commit (`feature/` → minor, + based on the source branch named in the head commit, which must be a + merge commit (`feature/` → minor, `bugfix/` / `hotfix/` → patch). - [conventional-commits](strategies/conventional-commits.md) bumps based on the head commit's Conventional Commits message diff --git a/docs/strategies/branch-prefix.md b/docs/strategies/branch-prefix.md index 5ed1032..c8ab7ce 100644 --- a/docs/strategies/branch-prefix.md +++ b/docs/strategies/branch-prefix.md @@ -1,7 +1,7 @@ # Branch-prefix strategy -The `branch-prefix` strategy inspects the subject line of each commit -and picks a bump if the subject (a) looks like a merge commit and +The `branch-prefix` strategy inspects the subject line of the head +commit on the default branch and picks a bump if the subject (a) looks like a merge commit and (b) contains a configured branch-name prefix. It is the default strategy because it works out-of-the-box on repos that merge via short-lived prefixed branches and use the default `git merge`