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.0.2) and keep all vociferate references on the same tag in a workflow.

Published composite actions:

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

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 valid credentials for release/comment API calls. On GitHub, secrets.GITHUB_TOKEN is used; on self-hosted Gitea, set secrets.GITEA_TOKEN.
• do-release and decorate-pr now 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. Prepare Then Publish

jobs:
  prepare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: prepare
        uses: git.hrafn.xyz/aether/vociferate/prepare@v1.0.2

  publish:
    needs: prepare
    uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.2
    with:
      tag: ${{ needs.prepare.outputs.version }}
    secrets: inherit

2. Publish Existing Tag

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: publish
        uses: git.hrafn.xyz/aether/vociferate/publish@v1.0.2
        with:
          version: v1.2.3

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: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
        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: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.2
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
      - name: Decorate PR
        uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.2
        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)

Primary outputs:

• comment-id
• comment-url

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.