Skip to content

release: upload only the docs for a version that hex.pm lists - #91

Merged
rubas-agent[bot] merged 1 commit into
mainfrom
publish-docs-rerun
Nov 14, 2026
Merged

rubas-agent[bot] merged 1 commit into
mainfrom
publish-docs-rerun

Conversation

@rubas-agent

@rubas-agent rubas-agent Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Before

AGENTS.md, release step 7, tells the owner how to recover a failed publish job:

When the job fails for a cause outside the repo, such as hex.pm or the workload identity, fix it and re-run the job.

The re-run runs the same command as the first run:

          mix hex.publish --yes 2>&1 | tee "$RUNNER_TEMP/publish.log"

Problem

When the docs upload fails, the release still waits on hex.pm without docs, and the job turns red (#90). Once an owner approves that release, a re-run uploads the package again. hex.pm refuses it with must include the --replace flag to update an existing release, and Hex then skips the docs. The version stays on Hex without docs, and the job stays red on every re-run.

After

The step asks hex.pm whether it lists the version. If it does, the step runs mix hex.publish docs --yes, and the docs wait for approval like a release. If it doesn't, the step runs mix hex.publish --yes as before. A re-run is now the one recovery, before and after the approval.

Case Before After
Re-run after an owner approved whisper_cpp 0.5.1 without docs job red, docs missing job green, docs staged
First run of a new version mix hex.publish --yes same
hex.pm answers 503 to the check no check job red before any upload
Details

The publish job came with #86, and #90 made it fail on Publishing docs failed and pointed the owner to a re-run. In Hex 2.7.0, Mix.Tasks.Hex.Publish.create/3 uploads the docs only after the package upload succeeds. On hex.pm, Hexpm.Repository.Release.update/7 rejects a second upload of a version without --replace, and StagedReleases.stage_docs/5 accepts docs for a staged or a published version. Before the approval, hex.pm answers 404 for a staged version, so a re-run uploads the package again, and Hex replaces the staged release with one that has docs.

Any answer other than 200 or 404 fails the step, so the job never guesses which upload Hex needs.

The repo has no test for its workflows. A throwaway harness ran the step from origin/main and from this branch with a fake mix that answers like Hex 2.7.0, and with the real hex.pm answer for 0.5.1 (200) and 9.9.9 (404). It gave the table above. zizmor 1.32.0 --persona=pedantic passes.

The same change merged in rubas/cloaked_req#94, rubas/exmpeg#102, rubas/kagi_ex#55, and rubas/whisper_ct2#106. AGENTS.md needs no change: "re-run the job" is now right in every state.

A re-run of the publish job after a failed docs upload ran mix hex.publish
again. Once an owner approved the staged release, Hex refused the package
upload without --replace and skipped the docs, so the version stayed
without docs.
@rubas-agent
rubas-agent Bot merged commit cf54738 into main Nov 14, 2026
1 check passed
@rubas-agent
rubas-agent Bot deleted the publish-docs-rerun branch November 14, 2026 08:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant