release.yml

# =========================================================================
#   MadScienceLab Docker Images
#   ThrowTheSwitch.org
#   SPDX-License-Identifier: MIT
# =========================================================================

# -----------------------------------------------------------------------
# Release Workflow
#
# Purpose:
#   Generate, lint, and validate all four Docker image variants (as in
#   ci.yml), additionally performing a real multi-platform docker buildx
#   build for each and pushing it to Docker Hub, then publish a full
#   GitHub release with release notes extracted from docs/Changelog.md
#   and the generated Dockerfile/asset artifacts attached.
#
# Trigger:
#   Push of a tag matching: v*.*.*  (e.g. v1.1.2, v1.1.2a)
#
#   Important: the v*.*.* glob also matches pre-release tags
#   (e.g. v1.1.2a-pre.1). The 'if' guard on the publish job provides a
#   second line of defense: any tag containing a hyphen is rejected and
#   the publish job is skipped, so only clean version tags (no -pre.N
#   suffix) produce a full release.
#
# Tag convention:
#   v1.1.2        full release, no image-only revision
#   v1.1.2a       full release, lowercase letter = image-only revision
#   v1.1.2a-pre.1 pre-release of the above (handled by prerelease.yml)
#
# Changelog lookup:
#   The docs/Changelog.md section header must match the tag's version
#   string verbatim (after stripping the leading 'v'), letter suffix
#   included, e.g. tag v1.1.2a looks up header "# [1.1.2a]". If no
#   matching section is found, GitHub's auto-generated release notes are
#   used instead.
#
# Related workflows:
#   ci.yml         — runs on every push/PR; validation only, no build
#   prerelease.yml — triggered by pre-release tags (v*.*.*-pre.*); also
#                    performs a real multi-platform build, but no push
# -----------------------------------------------------------------------

name: Release

on:
  push:
    tags:
      - 'v*.*.*'
      - '!v*.*.*-*'   # Exclude pre-release tags (e.g. v1.1.2-pre.1, v1.1.2a-pre.1)

# contents: write is required to create and upload GitHub releases.
# packages/attestations/id-token: write are required because the called
# _build-variant.yml reusable workflow's job requests them (for the real
# multi-platform build + push here) — a reusable workflow's job can't
# request more permissions than its caller grants, so these must be listed
# here even though this workflow's own `publish` job only needs
# contents:write.
permissions:
  contents: write
  packages: write
  attestations: write
  id-token: write

jobs:
  build:
    name: "Build ${{ matrix.image_name }}"
    strategy:
      fail-fast: false
      matrix:
        include:
          - image_name: madsciencelab
            image_dir: build/standard
            dir_args: '--dir build/standard'
          - image_name: madsciencelab-plugins
            image_dir: build/plugins
            dir_args: '--dir build/standard --dir build/plugins'
          - image_name: madsciencelab-arm-none-eabi
            image_dir: build/arm-none-eabi
            dir_args: '--dir build/arm-none-eabi'
          - image_name: madsciencelab-arm-none-eabi-plugins
            image_dir: build/arm-none-eabi-plugins
            dir_args: '--dir build/arm-none-eabi --dir build/plugins --dir build/arm-none-eabi-plugins'
    uses: ./.github/workflows/_build-variant.yml
    with:
      image_name: ${{ matrix.image_name }}
      image_dir: ${{ matrix.image_dir }}
      dir_args: ${{ matrix.dir_args }}
      version: ${{ github.ref_name }}
      build: true
      push: true
    secrets: inherit

  publish:
    name: "Publish Release"
    needs: build
    # Rejects tags that contain a hyphen (e.g. v1.1.2a-pre.1), which would
    # otherwise match the v*.*.* trigger glob and create a spurious full
    # release instead of leaving it to prerelease.yml
    if: ${{ !contains(github.ref_name, '-') }}
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: 'Checkout GitHub Action'
        uses: actions/checkout@v4

      - name: 'Download all variant artifacts'
        uses: actions/download-artifact@v4
        with:
          # `pattern:` is a workaround to an artifact upload incompatibility with docker/build-push-action@v6
          # https://github.com/docker/build-push-action/issues/1167
          pattern: "madsciencelab*"
          path: artifacts

      # Build the release body from release-notes-template.md followed by
      # the docs/Changelog.md section matching this tag's version. Strip
      # the leading 'v'; the tag itself contains no -pre.N suffix here
      # (guaranteed by the job-level 'if' guard above).
      - name: 'Build Release Notes'
        id: changelog
        shell: bash
        run: |
          SEMVER="${GITHUB_REF_NAME#v}"
          BODY_FILE="${RUNNER_TEMP}/release_body.md"

          cat .github/workflows/release-notes-template.md > "$BODY_FILE"
          echo "" >> "$BODY_FILE"

          if .github/workflows/extract_changelog.sh "${SEMVER}" "docs/Changelog.md" "${RUNNER_TEMP}/changelog_section.md"; then
            cat "${RUNNER_TEMP}/changelog_section.md" >> "$BODY_FILE"
            echo "found=true" >> "$GITHUB_OUTPUT"
          else
            echo "found=false" >> "$GITHUB_OUTPUT"
          fi

      - name: 'Publish GitHub Release (changelog found)'
        if: steps.changelog.outputs.found == 'true'
        uses: ncipollo/release-action@v1
        with:
          prerelease: false
          allowUpdates: true
          name: ${{ github.ref_name }}
          bodyFile: ${{ runner.temp }}/release_body.md
          artifacts: "artifacts/*/*.zip"

      - name: 'Publish GitHub Release (changelog not found, auto notes appended)'
        if: steps.changelog.outputs.found != 'true'
        uses: ncipollo/release-action@v1
        with:
          prerelease: false
          allowUpdates: true
          name: ${{ github.ref_name }}
          bodyFile: ${{ runner.temp }}/release_body.md
          generateReleaseNotes: true
          artifacts: "artifacts/*/*.zip"