diff --git a/.github/workflows/cd-github-release.yml b/.github/workflows/cd-github-release.yml index ded32b2..290fc39 100644 --- a/.github/workflows/cd-github-release.yml +++ b/.github/workflows/cd-github-release.yml @@ -8,7 +8,9 @@ on: type: string default: '"ubuntu-latest"' tag: - description: "Tag that triggered the release, e.g. v1.2.3." + description: >- + Tag to release, e.g. v1.2.3, or a component tag such as acme-blocks-v1.2.3 from a + multi-package release-please manifest. Its version selects the changelog section. type: string required: true artifact-name: @@ -28,15 +30,17 @@ on: type: string default: "" changelog-path: - description: "Path to the changelog whose matching section becomes the release body." + description: >- + Path to the changelog whose matching section becomes the release body. Ignored when a + release for the tag already exists, e.g. one release-please created. type: string default: "CHANGELOG.md" draft: - description: "Create the GitHub Release as a draft." + description: "Create the GitHub Release as a draft. Ignored when a release for the tag already exists." type: boolean default: false prerelease: - description: "Mark the GitHub Release as a prerelease." + description: "Mark the GitHub Release as a prerelease. Ignored when a release for the tag already exists." type: boolean default: false working-dir: @@ -69,6 +73,22 @@ jobs: - name: Checkout repository uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + # If the release already exists (e.g. made by release-please), only attach the asset. + - name: Check for an existing release + id: existing + shell: bash + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + TAG: ${{ inputs.tag }} + run: | + set -euo pipefail + if gh release view "$TAG" --json tagName >/dev/null 2>&1; then + echo "exists=true" >> "$GITHUB_OUTPUT" + else + echo "exists=false" >> "$GITHUB_OUTPUT" + fi + - name: Download release artifact uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 with: @@ -77,6 +97,7 @@ jobs: - name: Extract changelog section id: notes + if: steps.existing.outputs.exists != 'true' shell: bash env: TAG: ${{ inputs.tag }} @@ -105,11 +126,14 @@ jobs: echo "::error::Changelog not found at '$CHANGELOG_PATH'" exit 1 fi + # Component tags reduce to their version, prerelease included: acme-blocks-v1.2.3-rc.1 -> 1.2.3-rc.1. ver="${TAG#v}" - # Capture the body under the heading whose first token matches the tag's - # version, tolerating "## v1.2.3", "## 1.2.3", "## [1.2.3]", "## [v1.2.3]" - # and an optional trailing " - date". Exact token compare keeps "## Unreleased" - # and "## v1.2.30" from matching "v1.2.3". + if [[ "$TAG" =~ ^(.+-)?v?([0-9]+\.[0-9]+\.[0-9]+.*)$ ]]; then + ver="${BASH_REMATCH[2]}" + fi + # Print the section under the heading that matches the version: + # "## v1.2.3", "## [1.2.3]" or release-please's "## [1.2.3](url) (date)". + # Exact match, so "## Unreleased" and "## v1.2.30" never match 1.2.3. awk -v ver="$ver" ' /^## / { if (capture) { exit } @@ -117,6 +141,7 @@ jobs: sub(/^##[ \t]+/, "", line) split(line, parts, /[ \t]+/) head = parts[1] + sub(/\]\(.*$/, "", head) gsub(/^\[|\]$/, "", head) sub(/^v/, "", head) if (head == ver) { capture = 1 } @@ -178,21 +203,31 @@ jobs: echo "::notice::Packaged ${#entries[@]} top-level entries into ${SLUG}.zip (root: ${SLUG}/)." echo "asset=${SLUG}.zip" >> "$GITHUB_OUTPUT" - - name: Create GitHub Release + - name: Create or update GitHub Release shell: bash env: GH_TOKEN: ${{ github.token }} TAG: ${{ inputs.tag }} ASSET: ${{ steps.asset.outputs.asset }} + EXISTS: ${{ steps.existing.outputs.exists }} DRAFT: ${{ inputs.draft }} PRERELEASE: ${{ inputs.prerelease }} run: | set -euo pipefail - args=(release create "$TAG" "$ASSET" --verify-tag --title "$TAG" --notes-file release-notes.md) - if [ "$DRAFT" = "true" ]; then - args+=(--draft) - fi - if [ "$PRERELEASE" = "true" ]; then - args+=(--prerelease) + if [ "$EXISTS" = "true" ]; then + echo "::notice::Release $TAG already exists; attaching $ASSET and leaving its notes, title, draft and prerelease state unchanged." + # --clobber: a rerun replaces the asset instead of failing. + if ! gh release upload "$TAG" "$ASSET" --clobber; then + echo "::error::Could not attach $ASSET to $TAG. If immutable releases are on, have release-please create a draft and publish it after this job." + exit 1 + fi + else + args=(release create "$TAG" "$ASSET" --verify-tag --title "$TAG" --notes-file release-notes.md) + if [ "$DRAFT" = "true" ]; then + args+=(--draft) + fi + if [ "$PRERELEASE" = "true" ]; then + args+=(--prerelease) + fi + gh "${args[@]}" fi - gh "${args[@]}" diff --git a/AGENTS.md b/AGENTS.md index 66093df..64ee1a2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -116,7 +116,7 @@ Use `bash -eo pipefail -c`, never bare `bash -c`: `-e` is not inherited, so a ba - The self-hosted runners are ARC pods on Ubuntu 24.04 x64 with a minimal image, not GitHub's `ubuntu-latest`. They have `git`, `curl`, `jq`, `zip`, `rsync`, `python3`, `gh` and `docker`, but no Docker Compose v2, `yq`, `pip`, `aws` or `svn`, and no Node or PHP until `setup-node`/`setup-php` run. wp-env needs Compose v2, so jobs that boot wp-env fail on these runners until the image or the workflow provides it. `/usr/local/bin` needs `sudo`, which is passwordless. Install what a step needs, pinned and checksum-verified, as `ci-self-check.yml` does for `actionlint` and `yq` and `cd-s3.yml` does for the AWS CLI. apt's `yq` is kislyuk's jq wrapper, not the mikefarah `yq` this repo uses. - `actionlint` shells out to whatever `shellcheck` is on `PATH`, and rule behaviour differs between shellcheck releases — a local pass does not guarantee a CI pass. Write shell that is clean on older versions too: prefer `guard || continue` and explicit `if` blocks over `A && B || C`, which SC2015 flags on shellcheck 0.10 and earlier. - A green `bin/check-workflows.sh` proves input *names* are right, not input *values*. A wrong `build-command` or `artifact-path` only surfaces in a real consumer run. -- `cd-github-release.yml` extracts release notes by matching a version heading in `CHANGELOG.md`, and deliberately fails rather than publishing empty notes. Cut `## Unreleased` to `## vX.Y.Z - YYYY-MM-DD` before tagging. +- `cd-github-release.yml` is for consumers, not this repo's own releases. It takes release notes from the `CHANGELOG.md` heading whose version matches the tag — `## v1.2.3 - 2026-10-01`, `## [1.2.3] - 2026-10-01` or release-please's `## [1.2.3](compare-url) (2026-10-01)`, with component tags such as `acme-blocks-v1.2.3` reduced to their version — and deliberately fails rather than publishing empty notes, so a hand-cut release renames `## Unreleased` to its version before tagging. When a release for the tag already exists, as release-please creates one, it only attaches the asset and leaves the notes alone. - Consumers pin `@v1`, never a branch such as `@release/v1.0.0`. A moving ref has already broken real consumer runs mid-change. ## PR instructions diff --git a/README.md b/README.md index bac20f6..8ee5af3 100644 --- a/README.md +++ b/README.md @@ -66,11 +66,81 @@ one `wp-cd.yml` call. | Workflow | What it does | Example | |---|---|---| | [`wp-cd.yml`](.github/workflows/wp-cd.yml) | CD orchestrator. One call fans out to `github`, `wporg` and `s3` from `deploy-target` | [example](examples/wp-cd.yml) | -| [`cd-github-release.yml`](.github/workflows/cd-github-release.yml) | GitHub Release from a tag + artifact, notes from `CHANGELOG.md` | [example](examples/cd-github-release.yml) | +| [`cd-github-release.yml`](.github/workflows/cd-github-release.yml) | GitHub Release from a tag + artifact, notes from `CHANGELOG.md`; attaches to the release instead when one exists | [example](examples/cd-github-release.yml) | | [`cd-wp-org.yml`](.github/workflows/cd-wp-org.yml) | WordPress.org SVN deploy | [example](examples/cd-wp-org.yml) | | [`cd-s3.yml`](.github/workflows/cd-s3.yml) | S3 upload + optional CloudFront invalidation | [example](examples/cd-s3.yml) | | [`cd-built-branch.yml`](.github/workflows/cd-built-branch.yml) | Force-pushes source + generated output to a deploy branch | [example](examples/cd-built-branch.yml) | +#### With release-please + +release-please creates the tag and the GitHub Release with `GITHUB_TOKEN`, which never starts an +`on: push: tags` workflow. Build and attach in the same workflow instead, gated on its output; +`cd-github-release.yml` sees the existing release and only uploads the zip: + +```yaml +# .github/workflows/release.yml +name: Release +on: + push: + branches: [main] +permissions: + contents: read +jobs: + release-please: + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + outputs: + release-created: ${{ steps.release.outputs.release_created }} + tag: ${{ steps.release.outputs.tag_name }} + steps: + - id: release + uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 + + build: + needs: release-please + if: needs.release-please.outputs.release-created == 'true' + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + build-command: npm run build:prod && npm run package + upload-artifact: true + artifact-name: acme-blocks + artifact-path: dist/acme-blocks + + release: + needs: [release-please, build] + permissions: + contents: write + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-github-release.yml@v1 + with: + tag: ${{ needs.release-please.outputs.tag }} + artifact-name: acme-blocks +``` + +`release-please-action` reads `release-please-config.json` and `.release-please-manifest.json` from +the repository root. For a manifest package at a path, read +`steps.release.outputs['plugins/acme-blocks--release_created']` and `…--tag_name` instead. + +With immutable releases enabled, a published release takes no new assets. Set `"draft": true` and +`"force-tag-creation": true` in `release-please-config.json`, and publish once the zip is attached: + +```yaml + publish: + needs: [release-please, release] + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Publish the draft release + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + TAG: ${{ needs.release-please.outputs.tag }} + run: gh release edit "$TAG" --draft=false +``` + ### Maintenance | Workflow | What it does | Example |