semvertag

https://github.com/modern-python/semvertag
Admin
semvertag is a public-OSS auto-tagger for GitLab/GitHub/Bitbucket repositories, providing a Python...
Tokens:8,501
Snippets:115
Trust Score:9
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install semvertag using uvx

Source: https://github.com/modern-python/semvertag/blob/main/README.md

Install the semvertag tool using the uvx command-line utility. This is the recommended installation method.

```sh
uvx semvertag tag
```

--------------------------------

### SemVerTag CLI Dry Run JSON Output Example

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

An example of the JSON output from a local semvertag CLI dry run, showing the schema version, strategy, calculated bump, status, and next tag.

```json
{"schema_version":"1.0","strategy":"branch-prefix","bump":"minor","status":"dry_run","tag":"0.6.0","commit":"abc1234..."}
```

--------------------------------

### GitHub Actions Workflow Setup

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

Minimal workflow snippet for using the GitHub-scoped GITHUB_TOKEN. Ensure 'permissions: contents: write' is set at the workflow level.

```yaml
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install --quiet --no-cache-dir 'uv>=0.4,<1'
      - run: uvx 'semvertag>=0.5.0,<1' tag
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Local SemVerTag CLI Dry Run Example

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

Demonstrates how to perform a dry run of the semvertag CLI locally to preview the next tag bump. The output is provided in JSON format.

```bash
uvx 'semvertag>=0.5.0' tag --dry-run --json
```

--------------------------------

### GitHub API: Create Tag

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

Example of creating a tag on GitHub using the POST /repos/{owner}/{repo}/git/refs endpoint.

```python
POST /repos/{owner}/{repo}/git/refs
with {"ref": "refs/tags/{name}", "sha": commit_sha}
```

--------------------------------

### Local or One-off semvertag Invocation

Source: https://github.com/modern-python/semvertag/blob/main/docs/index.md

This example demonstrates how to run semvertag locally or for one-off tasks using environment variables for authentication and project identification.

```sh
SEMVERTAG_TOKEN=<your-gitlab-token> \
SEMVERTAG_PROJECT_ID=<your-project-id> \
  uvx semvertag tag
```

--------------------------------

### GitLab API: Create Tag

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

Example of creating a tag on GitLab using the POST /api/v4/projects/{id}/repository/tags endpoint.

```python
POST .../repository/tags
with {"tag_name": name, "ref": commit_sha}
```

--------------------------------

### Configuring SemVerTag Strategy in GitHub Actions

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

Example of how to specify a 'conventional-commits' strategy for semvertag within a GitHub Actions workflow. Environment variables for strategy-specific configurations can also be passed.

```yaml
      - uses: modern-python/semvertag@v0
        with:
          strategy: conventional-commits
```

```yaml
      - uses: modern-python/semvertag@v0
        env:
          SEMVERTAG_BRANCH_PREFIX__MINOR: '["feat/"]'
```

--------------------------------

### Previewing Next Tag Bump with Dry Run

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

This example shows how to use the 'dry-run: true' option with the semvertag action to preview the next tag bump without actually creating a tag. This is useful for CI smoke tests or PR previews.

```yaml
- id: semvertag
  uses: modern-python/semvertag@v0
  with:
    dry-run: true
```

--------------------------------

### GitLab CI Job for semvertag

Source: https://github.com/modern-python/semvertag/blob/main/docs/index.md

This snippet shows how to integrate semvertag into a GitLab CI pipeline. It specifies the Docker image, sets the strategy, installs the tool, and runs the tag command.

```yaml
semvertag:
  image: python:3.13-slim
  variables:
    SEMVERTAG_STRATEGY: branch-prefix  # or: conventional-commits
  before_script:
    - pip install --quiet 'uv>=0.4,<1'
  script:
    - uvx 'semvertag>=0.1,<1' tag
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

--------------------------------

### Use semvertag in GitLab CI

Source: https://github.com/modern-python/semvertag/blob/main/README.md

This GitLab CI job snippet demonstrates how to integrate semvertag into your CI pipeline. It installs semvertag and runs the tag command on the default branch. Ensure you have the correct SEMVERTAG_STRATEGY variable set.

```yaml
stages: [tag]

semvertag:
  stage: tag
  image: python:3.13-slim
  variables:
    SEMVERTAG_STRATEGY: branch-prefix  # or: conventional-commits
  before_script:
    - pip install --quiet 'uv>=0.4,<1'
  script:
    - uvx 'semvertag>=0.5.0,<1' tag
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

--------------------------------

### HTTP Client Configuration

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

Illustrates the configuration of an httpware.Client for forge interactions, including base URL, timeout, auth headers, and retry middleware.

```python
httpware.Client(
    base_url=provider.endpoint,
    timeout=settings.request_timeout,
    middleware=httpware.Retry(status_codes={408, 429, 500, 502, 503, 504}),
)
```

--------------------------------

### Use semvertag in GitHub Actions

Source: https://github.com/modern-python/semvertag/blob/main/README.md

This GitHub Actions workflow demonstrates how to use the modern-python/semvertag action. It checks out the repository with fetch-depth 0 to ensure full tag history is available, which is crucial for semvertag to function correctly.

```yaml
name: semvertag
on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: modern-python/semvertag@v0
```

--------------------------------

### Link Header Pagination Logic

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

Demonstrates parsing RFC 8288 Link headers to find the next page URL, ensuring it remains on the same origin.

```python
next_page_url(response, current_url=request.url)
same_origin(next_url, endpoint)
```

--------------------------------

### Mocking HTTP Transport with httpx2.MockTransport

Source: https://github.com/modern-python/semvertag/blob/main/tests/integration/README.md

This approach is used in integration tests to simulate HTTP responses without making actual network requests. It involves injecting httpx2.MockTransport into the httpware.Client.

```python
httpware.Client(httpx2_client=httpx2.Client(transport=httpx2.MockTransport(handler), base_url=...))
```

--------------------------------

### Branch Prefix Strategy Logic

Source: https://github.com/modern-python/semvertag/blob/main/architecture/strategies.md

This strategy infers the version bump from the subject line of a merge commit. It checks for specific merge marks, then looks for minor or patch indicators.

```python
def decide(self, commit: Commit) -> Bump:
    subject = subject_line(commit.message)

    if not any(m in subject for m in self.config.merge_mark_texts):
        return Bump.NONE

    if any(m in subject for m in self.config.minor):
        return Bump.MINOR

    if any(m in subject for m in self.config.patch):
        return Bump.PATCH

    return Bump.NONE
```

--------------------------------

### Provider Protocol Definition

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

Defines the abstract contract for forge providers using typing.Protocol. Providers are matched by shape and registered in the IoC container.

```python
from typing import Protocol

class Commit(typing.NamedTuple):
    sha: str
    message: str

class Tag(typing.NamedTuple):
    name: str
    commit_sha: str

class Provider(Protocol):
    name: str

    def get_default_branch(self) -> str:
        ...

    def get_latest_commit_on_default_branch(self) -> Commit:
        ...

    def list_tags(self) -> list[Tag]:
        ...

    def create_tag(self, name: str, commit_sha: str) -> None:
        ...
```

--------------------------------

### Minimal GitLab CI Job for SemVerTag

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/gitlab.md

This is the minimum required configuration for a GitLab CI job to automatically tag commits on the default branch using semvertag. Ensure SEMVERTAG_TOKEN is set as a project-level masked CI/CD variable.

```yaml
stages: [tag]

semvertag:
  stage: tag
  image: python:3.13-slim
  resource_group: semvertag
  variables:
    SEMVERTAG_STRATEGY: branch-prefix
  before_script:
    - pip install --quiet --no-cache-dir 'uv>=0.4,<1'
  script:
    - uvx 'semvertag>=0.1,<1' tag
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

--------------------------------

### Conditional Release Job Based on SemVerTag Output

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/github.md

This workflow demonstrates how to trigger a downstream release job only when the semvertag action successfully creates a new tag. It checks the 'status' output of the semvertag step.

```yaml
name: semvertag-and-release
on:
  push:
    branches: [main]

jobs:
  tag-and-release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: semvertag
        uses: modern-python/semvertag@v0
      - if: steps.semvertag.outputs.status == 'created'
        run: |
          echo "tagged ${{ steps.semvertag.outputs.tag }}"
          echo "bump=${{ steps.semvertag.outputs.bump }}"
```

--------------------------------

### Set SemVerTag Strategy in GitLab CI

Source: https://github.com/modern-python/semvertag/blob/main/docs/providers/gitlab.md

Configure the SEMVERTAG_STRATEGY variable in your .gitlab-ci.yml file to choose between 'branch-prefix' and 'conventional-commits'. This is typically done within the semvertag job definition.

```yaml
semvertag:
  # ...
  variables:
    SEMVERTAG_STRATEGY: conventional-commits
```

--------------------------------

### Conventional Commits Strategy Logic

Source: https://github.com/modern-python/semvertag/blob/main/architecture/strategies.md

This strategy derives the version bump from a Conventional Commits header in the commit subject and body. It prioritizes breaking changes over type-based bumps.

```python
def decide(self, commit: Commit) -> Bump:
    match = self.header_pattern.match(commit.message)
    if not match:
        return Bump.NONE

    type, scope, bang = match.group("type"), match.group("scope"), match.group("bang")

    if any(line.startswith("BREAKING CHANGE:") or line.startswith("BREAKING-CHANGE:") for line in commit.body_lines):
        return Bump.MAJOR

    if bang:
        return Bump.MAJOR

    if type in self.config.minor_types:
        return Bump.MINOR

    if type in self.config.patch_types:
        return Bump.PATCH

    return Bump.NONE
```

--------------------------------

### Disabling Retry Sleeps with Monkeypatch

Source: https://github.com/modern-python/semvertag/blob/main/tests/integration/README.md

This snippet demonstrates how to disable the sleep functionality within httpware's retry mechanism during integration tests. It patches the global time.sleep function to do nothing, preventing tests from waiting on retry backoffs.

```python
monkeypatch.setattr(time, "sleep", lambda *_a, **_k: None)
```

--------------------------------

### Secret Redaction Function

Source: https://github.com/modern-python/semvertag/blob/main/architecture/providers.md

The redact function substitutes known token patterns with '***' to prevent secret leakage in output.

```python
redact(text: str) -> str:
    """Substitutes *** for known token shapes."""
    ...

# Example usage in output handlers:
RichOutput.emit(redact(result_envelope))
JsonOutput.error(redact(error_message))
```
Tokens:
Raw