vociferate/AGENTS.md

Agent Integration Guide

This guide is for agentic coding partners that need to integrate the composite actions published by this repository.

Source Of Truth

Pin all action references to a released tag (for example @v1.2.0) and keep all vociferate references on the same tag in a workflow.

Published composite actions:

• https://git.hrafn.xyz/aether/vociferate@v1.2.0 (root action)
• https://git.hrafn.xyz/aether/vociferate/prepare@v1.2.0
• https://git.hrafn.xyz/aether/vociferate/publish@v1.2.0
• https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0
• https://git.hrafn.xyz/aether/vociferate/decorate-pr@v1.2.0

Action Selection Matrix

Use this when deciding which action to call:

• Choose prepare when you need to update changelog/version files, commit, and push a release tag.
• Choose publish when a tag already exists and you need to create or update release notes/assets.
• Choose coverage-badge after tests have produced coverage.out and you need coverage artefacts uploaded.
• Choose decorate-pr to annotate pull requests with coverage information and unreleased changelog entries.
• Choose root vociferate for direct recommend/prepare logic without commit/tag/push behavior.

Preconditions

Apply these checks before invoking actions:

• Checkout repository first.
• For prepare/publish flows that depend on tags/history, use full history checkout (fetch-depth: 0).
• Use secrets.RELEASE_PAT for release/tag/update operations (prepare, publish, release, update-release) so authenticated release changes can be pushed and published reliably.
• release, update-release, and decorate-pr run preflight API checks and fail fast when token credentials are missing or insufficient.
• Set required vars/secrets for coverage uploads:
  • vars.ARTEFACT_BUCKET_NAME
  • vars.ARTEFACT_BUCKET_ENDPONT
  • secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY
  • secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET
• For externally visible changelog links, set vars.VOCIFERATE_REPOSITORY_URL to the server/base URL only.

Changelog Format Guidance

Agents should keep CHANGELOG.md in a Keep a Changelog compatible structure because vociferate derives versions and release notes from headings.

Required conventions:

• Keep the top-level heading as # Changelog.
• Maintain an ## [Unreleased] section.
• Keep the standard subsections under Unreleased in this order:
  • ### Breaking
  • ### Added
  • ### Changed
  • ### Removed
  • ### Fixed
• Record releases with headings like ## [1.2.3] - YYYY-MM-DD.
• Use bullet entries under subsections (for example - Added new publish output).
• Preserve or regenerate bottom reference links ([Unreleased]: ..., [1.2.3]: ...) instead of mixing inline heading links.

Semver behavior used by recommendation logic:

• Breaking or Removed entries trigger a major bump.
• Added entries trigger a minor bump.
• Otherwise recommendation falls back to a patch bump.

Minimal template:

# Changelog

## [Unreleased]

### Breaking

### Added

### Changed

### Removed

### Fixed

Minimal Integration Patterns

1. Full Release Workflow

jobs:
  release:
    uses: https://git.hrafn.xyz/aether/vociferate/.gitea/workflows/release.yml@v1.2.0
    with:
      version: ${{ inputs.version }}
    secrets: inherit

2. Update Existing Release Tag

jobs:
  release:
    uses: https://git.hrafn.xyz/aether/vociferate/.gitea/workflows/update-release.yml@v1.2.0
    with:
      tag: v1.2.3
    secrets: inherit

3. Coverage Badge Publication

jobs:
  coverage:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}

4. Decorate Pull Request With Coverage and Changes

jobs:
  coverage:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
      - name: Decorate PR
        uses: https://git.hrafn.xyz/aether/vociferate/decorate-pr@v1.2.0
        with:
          coverage-percentage: ${{ steps.badge.outputs.total }}
          badge-url: ${{ steps.badge.outputs.badge-url }}

Inputs And Outputs Cheatsheet

prepare

Common inputs:

• version (optional override)
• version-file (optional)
• version-pattern (optional)
• changelog (optional)

Primary output:

• version (resolved tag, for example v1.2.3)

publish

Common inputs:

• token (optional, defaults to workflow token)
• version (optional if running from tag ref)
• changelog (optional)

Primary outputs:

• release-id
• tag
• version

coverage-badge

Required inputs:

• artefact-bucket-name
• artefact-bucket-endpoint

Useful optional inputs:

• coverage-profile (default coverage.out)
• summary-file (append markdown summary)

Primary outputs:

• total
• report-url
• badge-url

decorate-pr

Required inputs:

• coverage-percentage (0-100, typically from coverage-badge action)
• badge-url (SVG badge URL, typically from coverage-badge action)

Useful optional inputs:

• changelog (default CHANGELOG.md)
• comment-title (default Vociferate Review)
• token (defaults to workflow token)
• enable-changelog-gate (default false) - Enable changelog validation gate
• changelog-gate-mode (default soft) - strict or soft mode for gate
• changelog-gate-required-for (default code,behavior,security,workflow,tooling) - Change types requiring entries
• changelog-gate-allow-docs-only (default true) - Skip requirement for docs-only PRs
• changelog-gate-docs-globs (default docs/**,**.md,**.txt,**.rst) - Docs file patterns
• changelog-gate-skip-labels (default empty) - PR labels that bypass requirement

Primary outputs:

• comment-id - Comment ID
• comment-url - Comment URL
• gate-passed - Whether changelog gate validation passed
• docs-only - Whether PR is docs-only
• unreleased-additions-count - Number of Unreleased additions detected
• gate-failure-reason - Reason for gate failure, if applicable

Guardrails For Agents

Use these rules to avoid common automation mistakes:

• Do not mix action tags in one workflow update.
• Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported.
• Do not treat VOCIFERATE_REPOSITORY_URL as a full repository URL; it must be a base URL.
• Do not bypass preflight failures with broad retry loops; fix token scope/secret wiring first.