jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/pdftract-2x7y.md
jedarden 5485a15550 docs(pdftract-2x7y): add verification note for pdftract-github-release 
Documents the implementation of the pdftract-github-release
WorkflowTemplate, including artifact taxonomy, release notes
generation, and acceptance criteria status.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 19:23:39 -04:00

4.7 KiB
Raw Blame History

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