Add support for automated release creation via GitHub Tags

[zcorrea357]

Add support for automated release creation via GitHub Tags

Summary

Implement an “auto-release” workflow that automatically creates a new GitHub Release whenever a tag is pushed. This will streamline our release process—especially for organizations on GitHub’s free plan that cannot use paid Actions like actions/create-release.

Motivation

Currently our repository lacks an automated way to publish releases. Manually creating releases is error‑prone and time consuming. By adding a simple shell‑script‑based workflow in .github/workflows/publish.yml, we enable zero‑touch release creation without requiring paid GitHub features.

Proposed Implementation

Use a shell script within a YAML workflow (instead of a proprietary Action) to call the GitHub REST API and create a release. This approach matches the implementation in these reference repositories:

• Superlinear Substrate: https://github.com/superlinear-ai/substrate
• ThreatXManager (example workflow): https://github.com/CorreaCyberLabsLTD/threatXmanager/blob/main/.github/workflows/publish.yml

Key points

• Trigger: on: push with tags: ['v*.*.*']
• Steps:
  1. Checkout code
  2. Use curl (or gh release create) in a shell script
  3. Populate release title/body from tag name and changelog (optional)

Acceptance Criteria

• New workflow file under .github/workflows/publish.yml
• Releases automatically created when pushing tags matching v*.*.*
• No paid Actions or marketplace dependencies
• Documentation updated in README

References

• Superlinear Substrate repo: https://github.com/superlinear-ai/substrate
• ThreatXManager example workflow: https://github.com/CorreaCyberLabsLTD/threatXmanager/blob/main/.github/workflows/publish.yml

[zcorrea357]

jobs:
  release:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/astral-sh/uv:0.6.5-python3.10-bookworm

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch full history (all tags and commits)

      - name: Configure Git safe directory
        run: |
          git config --global --add safe.directory "$GITHUB_WORKSPACE"

      - name: Install jq
        run: |
          apt-get update && apt-get install -y jq

      - name: Create GitHub Release using CHANGELOG block
        id: release
        run: |
          # Enable strict error handling for robustness
          set -euo pipefail

          # Extract the current tag name (e.g., v0.1.0)
          TAG=${GITHUB_REF#refs/tags/}

          # If CHANGELOG.md exists, extract the block starting with the header "## ${TAG}"
          if [ -f CHANGELOG.md ]; then
            DESCRIPTION=$(awk 'BEGIN {flag=0} {if($0 ~ "^## '"$TAG"'") {flag=1} else if(flag==1 && $0 ~ "^## ") {exit} if(flag==1) print}' CHANGELOG.md)
            # Fallback if the extracted block is empty
            if [ -z "$DESCRIPTION" ]; then
              DESCRIPTION="Automated release for ${TAG}"
            fi
          else
            DESCRIPTION="Automated release for ${TAG}"
          fi

          # Create the JSON payload using jq
          PAYLOAD=$(jq -n \
            --arg tag "$TAG" \
            --arg name "$TAG" \
            --arg body "$DESCRIPTION" \
            '{ tag_name: $tag, name: $name, body: $body, draft: false, prerelease: false }')

          # Create the release via GitHub API
          RESPONSE=$(curl -sSL \
            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
            -H "Accept: application/vnd.github+json" \
            https://api.github.com/repos/${{ github.repository }}/releases \
            -d "$PAYLOAD")

          # Extract the release ID from the response and set it as the step output
          RELEASE_ID=$(jq -r '.id // empty' <<<"$RESPONSE")
          echo "::set-output name=release_created::$RELEASE_ID"
        shell: bash

[lsorber]

Hi @zcorrea357, thanks for the suggestion!

Currently, the template will automatically publish to PyPI when you create a GitHub release:

substrate/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if project_type == 'package' %}publish.yml{% endif %}.jinja

Lines 3 to 6 in ed49693

	on:
	release:
	types:
	- created

This way you have control over which tags you actually want to publish to a package index like PyPI, because you may not want to publish every tag to PyPI.

Does that work for you? If not, could you elaborate on why not?

[zcorrea357]

Hi @lsorber, thanks for the feedback! 🙏

Currently, our workflow requires someone to manually navigate to GitHub’s UI after pushing a tag and click “Draft a new release.” In other words, creating a tag does not automatically generate a GitHub Release. This manual step introduces extra work and increases the risk of inconsistencies (e.g., forgetting to include changelog entries or using an incorrect title).

You mentioned that our template already publishes to PyPI when a Release is created — but that creation step remains manual. For organizations (like ours) on GitHub’s free tier, we don’t have access to paid Actions (such as actions/create-release) or marketplace workflows that automate Release creation.

Automating Release creation on a tag push (matching v*. *. *) eliminates this friction. Additionally:

1. Tag vs. Release: A tag simply marks a commit in the repository, whereas a Release is the formal version milestone that triggers PyPI publication and provides structured changelogs for end users.
2. Automating this step means pushing a tag automatically creates the Release, publishes to PyPI, and pulls in the relevant CHANGELOG block — making the process more professional, robust, and error‑proof.
3. It relies solely on curl + the GitHub REST API with the built‑in ${{ secrets.GITHUB_TOKEN }}, so there’s no dependency on paid GitHub features.

In short, the proposed workflow turns a tag push into a zero‑touch pipeline that consistently creates a GitHub Release and publishes to PyPI without manual intervention — aligning our template with CI/CD best practices for Python packages.