hex-release

name	hex-release
description	Guides interactive Hex package release for AgentJido repos. Supports automated (GitHub Actions workflow_dispatch) and manual release flows. Uses git_ops for version bumping and changelog generation. Triggers on: release, hex publish, bump version, new release, publish package.

Hex Release (Human-in-the-Loop)

Interactive workflow for releasing a Hex package with manual verification at each step. Supports two release paths: automated (via GitHub Actions) and manual (local).

When to Use

Use this skill when asked to:

• Release a new version to Hex
• Bump the package version
• Prepare a release
• Create a release tag
• Trigger a release workflow

Pre-flight Checks

Before starting, run these checks automatically:

1. Identify the Package

Read mix.exs to determine:

• Package name (from project() → :name or :app)
• Current version (from @version or project() → :version)
• Whether it has git_ops as a dependency (required for automated release)

2. Check for Git Dependencies

grep -E 'github:|git:|path:' mix.exs

Categorize any git/path deps found:

• dev/test only (only: [:dev, :test]): Will not block Hex publish — note but continue
• runtime deps: STOP — these block mix hex.publish. Tell the user which deps need to be published to Hex first or switched to Hex versions

3. Git Status

git status --porcelain

If dirty, STOP and ask user to commit or stash changes first.

4. Verify Branch

git branch --show-current

Confirm user is on main. Warn if on a different branch.

5. Check for Releasable Commits

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD

If no commits since last tag, STOP — nothing to release.

Review commits and confirm they follow conventional commit format (feat:, fix:, chore:, etc.). Non-conventional commits won't be picked up by git_ops for the CHANGELOG.

6. Run Tests

mix test

If tests fail, STOP and show failures.

7. Run Quality Checks

mix quality

This typically runs: format check, compile with warnings-as-errors, credo, and dialyzer. If the alias doesn't exist, run mix format --check-formatted && mix compile --warnings-as-errors as a minimum. If any check fails, STOP and show the issues.

8. Hex Publish Dry Run

mix hex.publish --dry-run

Verify the package metadata and file list look correct.

If this fails only because no local Hex user is authenticated, treat that as a local environment limitation, not a package configuration failure:

• Show the package metadata/file list output to the user
• Note that CI still requires a configured HEX_API_KEY secret to perform the real publish
• Continue if everything else in the dry run looks correct

If it fails for any other reason, STOP.

SHOW USER: Summary of all pre-flight results and current version.

ASK USER: "All checks passed. Which release path: automated (GitHub Actions) or manual (local)?"

---

Path A: Automated Release (GitHub Actions)

The AgentJido repos have a reusable release workflow triggered via workflow_dispatch. Many repos are already configured, so prefer verifying the existing workflow before proposing file changes.

Step 1: Confirm Workflow Exists

Check that .github/workflows/release.yml exists and calls:

uses: agentjido/github-actions/.github/workflows/elixir-release.yml@main

If that wrapper already exists, treat the repo as configured. Do not rewrite it just to match another repo byte-for-byte if it already delegates to the shared workflow and only adds compatible inputs.

Also verify the repo can actually publish:

• Confirm git_ops is present and configured locally
• Confirm the release workflow uses secrets: inherit
• Confirm a HEX_API_KEY secret is available in GitHub Actions, or ask the user to verify it if you cannot inspect secrets directly
• Warn if the user is not preparing to release from main

Step 2: Explain Dispatch Options

TELL USER:

The release workflow supports these options:

  • dry_run: true     — Full dry run (no git push, no tag, no Hex publish)
  • hex_dry_run: true — Runs git_ops release + push, but skips actual Hex publish
  • skip_tests: true  — Skip test step (use if CI already passed)
  • version_override: X.Y.Z — Force a specific bare SemVer version when the workflow supports it

Recommended first run: dry_run: true

Step 3: Trigger the Workflow

Option 1 — GitHub CLI (if gh is available):

# Dry run first
gh workflow run release.yml -f dry_run=true

# Watch the run
gh run list --workflow=release.yml --limit=1
gh run watch

If the repo supports explicit version override:

gh workflow run release.yml -f dry_run=true -f version_override=1.2.3

Option 2 — GitHub UI:

1. Go to: https://github.com/agentjido/{REPO}/actions/workflows/release.yml
2. Click "Run workflow"
3. Set dry_run = true for first attempt
4. Click "Run workflow"

ASK USER: "Run a dry run first? (recommended)"

Step 4: Verify Dry Run Results

After the dry run completes:

gh run view --log-failed  # Check for errors

Review the workflow summary for:

• Version that would be released
• Hex publish dry-run output
• Any skipped steps

ASK USER: "Dry run succeeded. Ready to run the real release?"

Step 5: Trigger Real Release

gh workflow run release.yml
# Or with skip_tests if CI already passed:
gh workflow run release.yml -f skip_tests=true

If the repo supports explicit version override:

gh workflow run release.yml -f version_override=1.2.3

Step 6: Verify

gh run watch  # Wait for completion

TELL USER:

✅ Release triggered!

The workflow will:
  1. Run git_ops.release to bump version + update CHANGELOG
  2. Push the release commit and tag
  3. Publish to Hex.pm
  4. Create a GitHub Release

Monitor at: https://github.com/agentjido/{REPO}/actions
After publish, verify at: https://hex.pm/packages/{PACKAGE}

---

Path B: Manual Release (Local)

Use when the automated workflow isn't available, or for repos that can't publish to Hex (e.g., git deps blocking publish).

Step 1: Determine Version Bump

git_ops handles this automatically from conventional commits, but ask the user for confirmation.

Run the release in dry-run mode to preview:

mix git_ops.release --dry-run

This shows what version would be bumped to based on commit types:

• feat: commits → minor bump
• fix: commits → patch bump
• BREAKING CHANGE: → major bump

SHOW USER: The proposed version bump and commits that will be included.

ASK USER: "git_ops wants to release vX.Y.Z. Proceed, or override with a specific version?"

Step 2: Run the Release

# Let git_ops decide the version:
mix git_ops.release --yes

# Or force a specific version:
mix git_ops.release --yes --new-version X.Y.Z

This will:

• Bump the version in mix.exs
• Update CHANGELOG.md from conventional commits
• Create a release commit
• Create a git tag

SHOW USER: The release commit diff and tag.

Step 3: Review Before Pushing

git log --oneline -3
git diff HEAD~1
git tag -l | tail -5

ASK USER: "Release commit and tag created locally. Ready to push?"

Step 4: Push

git push origin main
git push origin --tags

Step 5: Publish to Hex

# Final dry-run check
mix hex.publish --dry-run

# Publish
mix hex.publish --yes

Step 6: Create GitHub Release

VERSION="v$(grep -m1 '@version "' mix.exs | sed 's/.*"\(.*\)".*/\1/')"
gh release create "$VERSION" \
  --title "Release $VERSION" \
  --notes "See [CHANGELOG.md](CHANGELOG.md) for details."

TELL USER:

✅ Release complete!

  Published: https://hex.pm/packages/{PACKAGE}
  GitHub:    https://github.com/agentjido/{REPO}/releases/tag/{VERSION}

---

Rollback

Before pushing:

git reset --soft HEAD~1          # Undo release commit
git tag -d v{VERSION}            # Delete local tag
git checkout mix.exs CHANGELOG.md  # Restore files

After pushing but before Hex publish:

git push origin :refs/tags/v{VERSION}  # Delete remote tag
git revert HEAD                         # Revert release commit
git push origin main

After Hex publish:

Hex packages cannot be unpublished after 1 hour. You can retire a version:

mix hex.retire {PACKAGE} {VERSION} invalid --message "Released in error"

---

Notes

• All AgentJido repos use conventional commits — non-conventional commits are ignored by git_ops
• The quality mix alias varies per repo — check mix.exs aliases section
• git_ops is a dev-only dependency — release commands run in MIX_ENV=dev
• The automated workflow uses GITHUB_TOKEN for git push and HEX_API_KEY (org secret) for Hex publish
• If a repo already has the standard reusable release.yml, prefer validating it with mix test, mix git_ops.release --yes --dry-run, and mix hex.publish --dry-run before changing workflow files
• Repos with runtime git dependencies (e.g., jido_runic) cannot publish to Hex — use manual path for git tag/release only, skip Hex publish step