feat(APP-963): modular release system — design + modules

[tyhonchik]

What & why

APP-963 (SEAL best-practices; blocks SREDO-695/697/698). Every Aragon repo re-implements a near-identical release pipeline. This design-first PR standardises them into loadable modules here, so secrets are handled the same way, the broad-permission Vercel token has one place it can be read, and a fix patches everywhere via one bump.

Deliverables

• docs/release-design.md — the study/design: scenarios A–D (app / library / backend / indexer), the Build → Test → Release → Deploy spine, the module catalog, the explicit-paths credential model, the security contract, and distribution/versioning. (primary deliverable)
• steps/ — 12 new composite actions incl. compute-version (the pluggable changesets | semantic-release seam). Scripts are co-located and called via $GITHUB_ACTION_PATH so the actions work cross-repo; generateReleaseSummary no longer hardcodes a repo.
• .github/workflows/ — reusable workflows: release-start, release-finalize, deploy-vercel, deploy-docker, e2e, release-self.
• examples/ — per-scenario caller workflows. Plus .github/dependabot.yml and a _selftest smoke workflow.

Key decisions

• Two version engines stay; the divergence is one pluggable action.
• Credentials: each repo passes its own op:// paths; one scoped OP_SERVICE_ACCOUNT_TOKEN; no secrets: inherit; inputs validated; third-party actions SHA-pinned.
• Distribution: semver + moving major (release-self); consumers pin SHAs + Dependabot.

Safety

Additive only — steps/credential-retrieval (v0.4, in use by app / app-backend / gov-ui-kit) is untouched, so existing @v0.4 SHA pins keep working. Migrating consumers is downstream (SREDO tickets).

Validation

• actionlint clean; all workflow/action YAML parses; node --check on all scripts.
• _selftest.yml (manual dispatch) smoke-tests the leaf actions in-repo.

Reviewer notes

• Self-references inside reusable workflows use aragon/github-templates/steps/*@main during bootstrap (relative ./steps/* would resolve against the caller repo). Pin these to the cut tag/SHA when releasing v0.5.
• Final SHA-pinning of third-party actions + cutting v0.5 / v1 is for the DevOps owner (CODEOWNER).

Update 2026-08-03: monorepo support

This PR was written before aragon/app became a pnpm monorepo. The app repo has since grown improved copies of several modules (scope-based changeset versioning, @aragon/app@x.y.z tags, workspace-aware Vercel deploys). This update ports those improvements back and parameterizes every release/deploy module so both repo shapes work from the same files: single-package repos use the defaults, monorepos pass inputs (package-dir, tag-prefix, scope, release-branch-prefix, workspace). gov-ui-kit and aragon-domain can adopt the modules now and migrate to monorepos later by changing inputs only.

• compute-version absorbs app's changeset-version: a scope input names an entry in the consumer's .github/release-scopes.yml and is inverted into changeset version --ignore flags against the live workspace list (new packages fail safe). Version and tag come from package-dir; new tag output.
• generate-release-summary merges the app script: tag-glob boundary (v* or @aragon/app@*), optional path filtering via .github/filters.yml, --first-parent, merge-commit title resolution.
• New steps: generate-version-summary (per-package PR body), changesets-guard (pending changesets at the release commit, scope-aware), gh-pr-get-body / gh-pr-edit-body.
• New lib/ with a vendored strict flat-YAML parser, so the two mapper files parse without consumer node_modules. Unit tests run via node --test (17 tests) and a new ci.yml on every PR.
• Bug fixes found while porting: release-start now stages the deleted .changeset/*.md (before, consumed changesets merged back to main and re-released next cycle); git identity is configured when no GPG key is passed; push --force became --force-with-lease; credential-retrieval metadata used workflow-only type:/options: keys, which composite actions reject (actionlint is clean again).
• release-finalize: merge-sha renamed to sha; the caller picks what to tag (tested head SHA, recommended, or merge commit).
• deploy-vercel unified with app's shared-deploy.yml: workspace, runtime env lifting, optional Sentry source maps, and the missing vercel pull step.
• New example examples/release-changesets-monorepo.yml; the design doc gains seam 3 (package location & repo shape).

Correction to "Safety" above: steps/credential-retrieval IS modified (byref mode + this update's metadata fix), but @v0.4 SHA pins are immutable and unaffected.

Validation: node --test 17/17, actionlint clean, node --check on all scripts. Both shapes simulated locally: a scratch single-package repo end-to-end (changeset → version → the staging includes the changeset deletion) and the app checkout (scope inversion produces the same --ignore flags as app's current changeset-version, version read from apps/app).