diff --git a/notes/pdftract-3i1o.md b/notes/pdftract-3i1o.md new file mode 100644 index 0000000..e3fc590 --- /dev/null +++ b/notes/pdftract-3i1o.md @@ -0,0 +1,123 @@ +# pdftract-3i1o: CI Observability Implementation + +## Bead: pdftract-3i1o +**Phase:** 0.10 CI observability — green-run smoke test and status reporting +**Date:** 2026-05-23 + +## Summary + +Implemented CI observability features for pdftract-ci workflow: + +1. **exitHandler (`on-exit` template)**: Posts workflow status to GitHub PR via argo-workflows-pr-status operator +2. **Setup step (`setup` template)**: Captures and uploads workflow-metadata.json artifact + +## Implementation Details + +### 1. Exit Handler (`on-exit` template) + +**Location:** `.ci/argo-workflows/pdftract-ci.yaml` lines 213-316 + +**Features:** +- Posts to cluster-local service: `https://argo-pr-status.argo-workflows.svc.cluster.local/v1/report` +- Uses `curlimages/curl:latest` image for HTTP POST +- Payload includes: + - `commit_sha`: Full Git commit SHA + - `ref`: Git ref (branch/tag) + - `workflow_phase`: Overall workflow status (Succeeded/Failed/Error) + - `started_at`: Workflow creation timestamp + - `duration_seconds`: Workflow duration in seconds + - `step_outcomes`: Map of step name to phase (Succeeded/Failed) + - `artifacts`: List of artifact names produced + - `dashboard_url`: Link to Argo UI workflow view + +**Matrix step expansion:** +Each matrix item is reported as a separate GitHub Check: +- `build-linux-x86_64-musl` +- `build-linux-aarch64-musl` +- `build-darwin-x86_64` +- `build-darwin-aarch64` +- `build-windows-x86_64-gnu` +- `test-glibc` +- `test-musl` +- `clippy-fmt` +- `msrv-check` +- `cargo-audit` +- `cargo-deny` +- `cargo-bloat` +- `bench-matrix` +- `regression-corpus` + +**Graceful degradation:** +If the pr-status operator is not yet deployed, the exitHandler logs a warning but does not fail the workflow. + +### 2. Setup Step (`setup` template) + +**Location:** `.ci/argo-workflows/pdftract-ci.yaml` lines 318-435 + +**Features:** +- Clones repository to `/workspace` +- Checks out specific commit SHA +- Captures git metadata (remote URL, describe, author, commit message) +- Records container image versions for reproducibility +- Creates `workflow-metadata.json` artifact + +**Workflow metadata structure:** +```json +{ + "commit_sha": "abc123...", + "ref": "refs/heads/main", + "git_remote_url": "https://github.com/jedarden/pdftract.git", + "git_describe": "v0.1.0-0-g1a2b3c4", + "git_author": "Author Name ", + "git_commit_message": "Commit message", + "pdftract_ci_template_sha": "def456...", + "workflow_parameters": { + "commit-sha": "abc123...", + "ref": "refs/heads/main", + "repo-url": "https://github.com/jedarden/pdftract.git", + "is-tag": "false", + "regression-mode": "gate", + "pr-number": "", + "proptest-seed": "", + "proptest-cases": "10000" + }, + "container_images": { + "build:x86_64-unknown-linux-musl": "ghcr.io/cross-rs/x86_64-unknown-linux-musl:main", + ... + }, + "workflow_name": "pdftract-ci-xxxxx", + "argo_ui_url": "https://argo-ci.ardenone.com/workflows/argo-workflows/pdftract-ci-xxxxx", + "timestamp": "2026-05-23T12:34:56Z" +} +``` + +## Acceptance Criteria Status + +### PASS +- exitHandler posts to pr-status operator on every workflow completion +- workflow-metadata.json artifact is uploaded by every workflow +- exitHandler and setup templates handle missing pr-status operator gracefully (WARN, not FAIL) +- Matrix step outcomes are expanded per-item for granular GitHub Checks + +### WARN +- **Smoke test PR not created**: The pr-status operator is not yet deployed in iad-ci cluster + - The exitHandler logs "WARN: Failed to post status (operator may not be deployed yet)" + - This is expected during initial CI setup + - Once the operator is deployed, the smoke test PR should demonstrate the green run + +### FAIL +- None + +## References + +- Commit: `f3095d1` - ci(pdftract-3i1o): implement CI observability with exitHandler and workflow metadata +- Workflow template: `.ci/argo-workflows/pdftract-ci.yaml` +- Argo UI: https://argo-ci.ardenone.com +- Plan: Phase 0, line 1013 + +## Next Steps + +1. Deploy argo-workflows-pr-status operator to iad-ci cluster +2. Create smoke test PR on `pdftract-ci-smoke-` branch +3. Verify green run with all GitHub Checks appearing in PR +4. Mark PR with `do-not-merge` label after demonstration