# 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 Rush](https://cloud.getrush.ai/run/add-release-workflow/elixir/). Opens 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`

```json
{
  "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.

## 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

- [Add Sobelow Security Scanning to a Phoenix App](https://getrush.ai/run/add-sobelow/elixir/)
- [Explain the Architecture of an Elixir Codebase](https://getrush.ai/run/architecture-overview/elixir/)
- [Fix Flaky Tests in an Elixir App](https://getrush.ai/run/fix-flaky-tests/elixir/)

## The same job on other stacks

- [Add a Release Workflow to a Custom GitHub Action](https://getrush.ai/run/add-release-workflow/github-actions/)
- [Add a GitHub Release Workflow to a Go CLI](https://getrush.ai/run/add-release-workflow/go-cli/)
- [Add a Release Workflow for a Jekyll Theme Gem](https://getrush.ai/run/add-release-workflow/jekyll/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
