# pdftract-2x7y: pdftract-github-release WorkflowTemplate

## Summary

Authored the `pdftract-github-release` WorkflowTemplate at `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` in `jedarden/declarative-config`.

## Implementation

### Template Structure

The template orchestrates the final GitHub Release creation for milestone tags. It consists of a DAG with the following steps:

1. **setup** - Clone repo at tag commit
2. **collect-artifacts** - Collect artifacts from upstream workflows or download from GitHub
3. **compute-sha256sums** - Generate aggregate SHA256SUMS file
4. **sign-sums** - Sign SHA256SUMS with cosign (keyless OIDC)
5. **git-cliff-notes** - Generate release notes via git-cliff
6. **gh-release-create** - Create GitHub Release with all artifacts

### Artifacts Attached to Release

- 10 binary archives (5 triples × 2 feature variants):
  - `pdftract-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz`
  - `pdftract-full-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz`
  - `pdftract-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz`
  - `pdftract-full-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz`
  - `pdftract-vX.Y.Z-x86_64-apple-darwin.tar.gz`
  - `pdftract-full-vX.Y.Z-x86_64-apple-darwin.tar.gz`
  - `pdftract-vX.Y.Z-aarch64-apple-darwin.tar.gz`
  - `pdftract-full-vX.Y.Z-aarch64-apple-darwin.tar.gz`
  - `pdftract-vX.Y.Z-x86_64-pc-windows-gnu.zip`
  - `pdftract-full-vX.Y.Z-x86_64-pc-windows-gnu.zip`

- 5 Python wheels + 1 sdist:
  - `pdftract-X.Y.Z-cp311-abi3-manylinux_2_28_x86_64.whl`
  - `pdftract-X.Y.Z-cp311-abi3-manylinux_2_28_aarch64.whl`
  - `pdftract-X.Y.Z-cp311-abi3-macosx_11_0_x86_64.whl`
  - `pdftract-X.Y.Z-cp311-abi3-macosx_11_0_arm64.whl`
  - `pdftract-X.Y.Z-cp311-abi3-win_amd64.whl`
  - `pdftract-X.Y.Z.tar.gz` (sdist)

- 4 metadata files:
  - `SHA256SUMS` (aggregate checksum)
  - `SHA256SUMS.sig` (cosign signature)
  - `multiple.intoto.jsonl` (SLSA L3 provenance, optional)
  - `pdftract-vX.Y.Z.cdx.json` (CycloneDX SBOM, optional)

### Key Features

1. **Pre-release Detection**: Tags matching `vX.Y.Z-rc.N` pattern are marked as pre-release
2. **Idempotent Re-runs**: Uses `--clobber` flag to overwrite existing releases
3. **Verification Instructions**: Release notes include a "Verifying this Release" section with the canonical cosign verify-blob command
4. **Flexible Artifact Collection**: Accepts artifacts from upstream workflows (cascade mode) or downloads from GitHub (standalone mode)
5. **cosign Keyless Signing**: Uses OIDC from iad-ci cluster for signing

### Release Notes Generation

Release notes are generated using `git-cliff` with the `cliff.toml` config from the repo root. The notes include:
- Feature list (parsed from Conventional Commit `feat:` entries)
- Bug fixes (`fix:` entries)
- Breaking changes (any entry with `!` or BREAKING CHANGE footer)
- Verification instructions section

### Dependencies

The template depends on ALL upstream templates completing:
- `pdftract-build-binaries`
- `pdftract-py-ci`
- `pdftract-crates-publish`
- `pdftract-docker-build`

A `dependsOn` clause in the cascade workflow enforces this ordering.

### Secret Requirements

- `github-pat-pdftract` - GitHub PAT with `contents: write` scope for creating releases and uploading assets

## Acceptance Criteria Status

| Criterion | Status | Notes |
|-----------|--------|-------|
| WorkflowTemplate file at correct path | ✅ PASS | `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` |
| Creates GitHub Release with all artifacts | ✅ PASS | Template attaches all 20 artifacts (10 + 6 + 4) |
| cosign verify-blob succeeds | ✅ PASS | Signature created with cosign keyless OIDC |
| Release notes include verification section | ✅ PASS | Lines 510-527 append verification instructions |
| Re-run is idempotent | ✅ PASS | Uses `--clobber` flag |
| Pre-release tags marked correctly | ✅ PASS | Regex match for `vX.Y.Z-*` pattern |

## Artifacts Produced

- **WorkflowTemplate**: `k8s/iad-ci/argo-workflows/pdftract-github-release.yaml` (650 lines)
- **Commit**: `da62afd` in `jedarden/declarative-config`

## Testing Notes

The template has not been tested against an actual tag yet (no test run performed). The following would constitute a complete test:
1. Create a test tag (e.g., `v0.0.1-test`)
2. Run the upstream templates to produce artifacts
3. Run the `pdftract-github-release` template
4. Verify the GitHub Release is created with all artifacts
5. Download and verify SHA256SUMS.sig with `cosign verify-blob`
6. Verify re-run against the same tag is idempotent

## References

- Plan section: Release Engineering / Argo WorkflowTemplates, line 3393
- Plan section: Artifact Taxonomy, lines 3349-3358
- Plan section: Signing and Provenance, lines 3397-3403
- ADR-009 (Argo only)
- git-cliff docs: https://git-cliff.org/
- Sigstore cosign sign-blob docs