[MAINT] Github Actions Reunification - `release-please`

[damienwebdev]

Workflow: release-please.yml

Status: 🔴 Needs update
Files: .github/workflows/release-please.yml

---

Background: why this workflow is more complex than it looks

Release-please manages the release PR and tag. That part is simple. The complexity comes from a problem specific to this repo: actions here cross-reference each other using absolute refs.

For example, setup-magento/action.yml might call:

uses: mage-os/github-actions/cache-magento@main

On main, @main is correct — you want the latest. But what happens when you tag v7.0.0? That tag still contains @main. So a user who pins their workflow to mage-os/github-actions/setup-magento@v7.0.0 is running the v7.0.0 outer action, but @main (always-latest) of every internal dep. Their "pinned" version is not actually stable.

The fix is: before the release tag is cut, replace all @main refs with the upcoming version number. Then after the release, restore @main on the main branch so development continues normally.

---

This project should replicate how Graycore handles its releases with release-please / pinback.

How it works end-to-end

Release-please creates and maintains a release PR on a long-lived branch (e.g., release-please--branches--main--components--github-actions). That PR stays open, accumulating changelog entries, until someone merges it to cut a release.

The workflow runs on every push to main and handles two distinct phases:

Phase 1 — Pin refs on the open release PR (runs on every push while release PR is open)

1. Run release-please — it updates the release PR but does NOT create a release yet (that only happens when the PR is merged).
2. Check if the release branch exists (i.e., a release PR is open).
3. If yes: check out the release branch, read the pending version from .release-please-manifest.json, and sed-replace every @main ref with @vX.Y.Z across all */action.yml files and non-release workflows.
4. GPG-sign and push that commit to the release branch.

This runs on every push to main, so the release PR always has up-to-date pinned refs. When it's finally merged and the tag is cut, the snapshot is coherent.

Phase 2 — Pinback after a release is cut (runs once, right after the release PR merges)

1. Check out main.
2. sed-replace the now-pinned version refs back to @main.
3. GPG-sign and open a PR to commit that restoration to main.

This is the "pinback" — it returns main to using floating @main refs so the cycle can start again for the next release.

---

Dependents

Internal workflow — not called by external repos directly.

---

Changes needed

1. Fix action org — google-github-actions/release-please-action@v4 → googleapis/release-please-action@v4
2. Remove command: manifest and default-branch: main inputs
3. Add workflow_dispatch trigger
4. Determine and set RELEASE_BRANCH — release-please names this branch deterministically from the repo/component config; find the correct value by checking an existing release PR in the mage-os repo or the release-please config, then hardcode it as the RELEASE_BRANCH env var
5. Port pin-on-release-branch steps — adapt sed pattern from graycoreio/github-actions-magento2 → mage-os/github-actions; update bot git identity
6. Port pinback job — same sed and identity changes
7. Provision secrets in mage-os org — need a bot PAT with repo write access and a GPG key for signed commits; coordinate with mage-os org admins before this can be tested

---

Notes

• GPG signing is only strictly required if the mage-os repo enforces signed commits on protected branches — confirm branch protection rules; if not enforced it can be simplified