# 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.1`) and keep all vociferate references on the same tag in a workflow. Published composite actions: - `git.hrafn.xyz/aether/vociferate@v1.0.1` (root action) - `git.hrafn.xyz/aether/vociferate/prepare@v1.0.1` - `git.hrafn.xyz/aether/vociferate/publish@v1.0.1` - `git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.1` - `git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.1` ## 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: ```markdown # Changelog ## [Unreleased] ### Breaking ### Added ### Changed ### Removed ### Fixed ``` ## Minimal Integration Patterns ### 1. Prepare Then Publish ```yaml 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.1 publish: needs: prepare uses: aether/vociferate/.gitea/workflows/do-release.yml@v1.0.1 with: tag: ${{ needs.prepare.outputs.version }} secrets: inherit ``` ### 2. Publish Existing Tag ```yaml 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.1 with: version: v1.2.3 ``` ### 3. Coverage Badge Publication ```yaml 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.1 with: artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }} artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }} ``` ### 4. Decorate Pull Request With Coverage and Changes ```yaml 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.1 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.1 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.