All jobs

Add a Release Workflow to an Elixir Library

Yes. An agent adds a tag-driven GitHub Actions workflow that checks version and changelog, runs tests, publishes to Hex and creates the release, then opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the library is versioned and tested before writing a release. In a library laid out like elixir-plug/plug, mix.exs holds @version "1.21.0-dev", a package() with licenses: ["Apache-2.0"], the maintainers, links to the changelog and GitHub, and the files list Hex ships; the docs config sets source_ref: "v#{@version}", and ex_doc is a dependency only: :docs, so docs build under MIX_ENV=docs. CHANGELOG.md opens with a ## v1.21.0-dev section above ## v1.20.3 (2026-07-09), so each release already has a heading to cut notes from. .github/workflows/ci.yml runs on pull requests and pushes to main with erlef/setup-beam@v1 over a matrix of Elixir 1.15 on OTP 24 and Elixir 1.19 on OTP 28, and on the newer pair also checks mix deps.get --check-locked, mix format --check-formatted and mix deps.unlock --check-unused before mix test.

The workflow goes in .github/workflows/release.yml, triggered by a push of a tag matching v* and by workflow_dispatch with a dry_run input. Its first job reads @version out of mix.exs with mix run --no-start -e and fails unless it equals the tag without its v, fails if the version still ends in -dev, and fails unless CHANGELOG.md has a ## v<version> heading with a date, so a tag pushed before the release commit stops here with a clear message. The second job runs mix deps.get and mix test on the newest matrix pair from ci.yml, so nothing is published that the suite does not pass on.

The publish job runs only on a tag, in a GitHub environment named hex whose single secret is HEX_API_KEY, which mix hex.publish reads from the environment. It runs MIX_ENV=docs mix deps.get and mix docs so the docs step of the publish has what it needs, then mix hex.build to show the tarball contents in the log, and mix hex.publish --yes to push the package and its docs; with dry_run set the job stops after hex.build. A last step extracts that version's section from CHANGELOG.md and runs gh release create with it as the notes, so the GitHub release and the Hex release carry the same text.

There is no test runner for a workflow, so the proof is in two parts. The agent runs the version and changelog check script locally against the current tree, which fails as it should on 1.21.0-dev, and against a scratch commit that sets 1.21.0 with a dated heading, which passes; it runs mix hex.build to confirm the files list in package() produces a tarball without the test directory. The workflow file itself is validated with actionlint, installed in the sandbox for the run, and the pull request pastes both outputs.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a release workflow to this Elixir library. Read mix.exs, CHANGELOG.md, README.md, .formatter.exs, .gitignore and .github/workflows/ci.yml first. Write .github/workflows/release.yml triggered by tags matching v* and by workflow_dispatch with a dry_run input. First job: read @version from mix.exs with mix run --no-start -e, fail unless it equals the tag without the v prefix, fail if it ends in -dev, and fail unless CHANGELOG.md has a `## v<version>` heading with a date. Second job: mix deps.get and mix test on the newest Elixir and OTP pair the CI matrix uses. Publish job, only on a tag, in a GitHub environment named hex that holds the Hex API key secret; it runs MIX_ENV=docs mix deps.get and mix docs, mix hex.build, then mix hex.publish --yes unless dry_run; then create a GitHub release whose notes are that version's CHANGELOG section. Put the check script in a file so it runs locally; run it against the current tree and against a scratch commit with a real version, run mix hex.build, run actionlint on the workflow, and open a pull request with the outputs. Do not create a tag, a release or a Hex package.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds .github/workflows/release.yml and a small check script under .github/, and a section in README.md or CONTRIBUTING.md describing the release steps: set the version and the changelog date in one commit, tag it v<version>, push the tag. Its description pastes the check script's two runs, the mix hex.build file list and the actionlint result. No tag, release or package is created by the run.

A maintainer who pushes a tag now gets one workflow run that either stops with a named reason before touching Hex or publishes the package, its docs and a GitHub release with the changelog section as notes. A tag that points at a -dev version, or one whose changelog heading is missing, never reaches the publish job, so Hex never sees a half-finished release that cannot be retracted.

Before merging, a reviewer creates the hex environment with the secret and restricts it to tag refs, decides who may approve a run in that environment, and confirms the Elixir and OTP pair the publish job builds docs with matches what ci.yml calls the latest supported.

Run it on every library still published from a laptop

A team that maintains several Hex packages starts one run per repository from the terminal: one POST /o/{org}/sessions each with that repository in resources and a request_id that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own mix.exs: a package whose version comes from a VERSION file reads that instead, an umbrella gets one publish step per child app, and a package that already has a release workflow gets only the version and changelog check.

Each run opens its own pull request on its own branch, and GET /o/{org}/sessions lists them newest first, so the person who started the batch reads every check output from one place and merges the packages in dependency order.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A release workflow is run rarely and fails loudly, usually with a package already on Hex that cannot be unpublished. The agent exercises the failure paths on purpose in its sandbox, running the version check against a -dev tree and a scratch release commit, building the tarball to see what ships, and linting the workflow, so the first real tag is not the first test.

The run keeps every command and its output, so the reviewer sees the tarball's file list and the check script's messages without installing Erlang and Elixir locally. Several packages can get the same workflow at once, each in its own sandbox, and one that already publishes from CI is left with a note instead of a second pipeline.

Frequently asked questions

Does the run publish anything?

No. The prompt says not to create a tag, a release or a package, and the sandbox has no HEX_API_KEY. The run proves the workflow with the check script, mix hex.build and actionlint; the first publish happens when a maintainer pushes a tag after the secret is set.

Why check the changelog heading?

Because source_ref in the docs config and the GitHub release notes both assume the version has a dated section. A tag pushed on a tree whose heading still reads -dev would publish docs that link to a tag with no notes. Failing before the publish job costs nothing; failing after it costs a version number.

Can a maintainer test the workflow without a tag?

Yes. workflow_dispatch with dry_run runs the checks, the tests and mix hex.build, and stops before hex.publish and the release. The same script runs locally with the tag name as its argument, which is how the agent tested it.

What does the hex environment add?

The secret lives only there, so a pull request from a fork or a run on another branch cannot read it, and the environment can require a named reviewer to approve before the job runs. Restricting it to tag refs means only a v* push reaches the publish step.

What about the OTP and Elixir versions for the published docs?

The publish job pins the newest pair from the CI matrix so the docs are built on a version the suite passes on. When ci.yml moves to a newer pair, the release workflow has one place to update, and the pull request notes it beside the matrix.

More Elixir jobs

The same job on other stacks

Keep reading