Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 51 additions & 16 deletions .github/workflows/cd-github-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -77,6 +97,7 @@ jobs:

- name: Extract changelog section
id: notes
if: steps.existing.outputs.exists != 'true'
shell: bash
env:
TAG: ${{ inputs.tag }}
Expand Down Expand Up @@ -105,18 +126,22 @@ 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 }
line = $0
sub(/^##[ \t]+/, "", line)
split(line, parts, /[ \t]+/)
head = parts[1]
sub(/\]\(.*$/, "", head)
gsub(/^\[|\]$/, "", head)
sub(/^v/, "", head)
if (head == ver) { capture = 1 }
Expand Down Expand Up @@ -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[@]}"
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
72 changes: 71 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Comment thread
Adi-ty marked this conversation as resolved.
Resolved
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 }}
Comment thread
Adi-ty marked this conversation as resolved.
Resolved
steps:
- id: release
uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0

build:
needs: release-please
if: needs.release-please.outputs.release-created == 'true'
Comment thread
Adi-ty marked this conversation as resolved.
Resolved
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 }}
Comment thread
Adi-ty marked this conversation as resolved.
Resolved
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 |
Expand Down
Loading