fix(release): repair Packagist publishing pipeline

[abbaseya]

Summary

Two related repairs to get the release pipeline functional. Without these, convertcom/php-sdk has zero installable versions on Packagist.

1. Fix the dead workflow_run trigger

.github/workflows/release.yml was waiting on workflows: ['CI'], but the CI workflow was renamed to Quality Checks (qa.yml) in commit f9b09cf. GitHub matches workflows: against the name: field, not the filename, so the release workflow has been silently dead since that rename:

• gh run list --workflow release.yml returns empty repo-wide.
• gh api repos/convertcom/php-sdk/tags returns [] — zero git tags ever.
• Packagist's /p2/convertcom/php-sdk.json reports versions: 0.

Changed to workflows: ['Quality Checks'].

2. Switch Packagist publish to API POST (off OAuth)

The current Packagist setup expects "connecting your GitHub account" — an OAuth grant tied to an individual GitHub user. For a company-owned package, that ties sync availability to whoever clicked Authorize: if they're removed from the org or revoke the grant, Packagist sync silently breaks. Routing the update through Packagist's API instead keeps the credential on the shared Packagist account (API token in repo secrets), with no individual GitHub identity in the loop.

Changes

.github/workflows/release.yml

• Trigger: workflows: ['CI'] → workflows: ['Quality Checks'] (matches qa.yml name: field).
• New step Notify Packagist of new release after Run semantic-release:
  • Gated on git describe --tags --exact-match HEAD — no-op when semantic-release didn't tag.
  • POSTs { repository: { url } } to https://packagist.org/api/update-package with PACKAGIST_USERNAME + PACKAGIST_API_TOKEN from repo secrets.
  • Repo URL derived from ${GITHUB_REPOSITORY} so it survives renames/forks.
  • curl -fsSL so a bad response fails the workflow loudly.

RELEASE.md

• Release-chain diagram + "Automated Flow" step 5 now describe the CI POST, not "Packagist webhook detects tag".
• "Packagist Setup" rewritten: register the package, generate a Packagist API token, add PACKAGIST_USERNAME and PACKAGIST_API_TOKEN as repo secrets. Explicit note that no GitHub OAuth grant ("connect your user account") is needed and why.
• Prerequisites checklist gained the secrets-configured item.
• Reactivation (split-publishing) section deliberately untouched.

What happens on merge

Verified by running yarn release --dry-run against this branch:

ℹ  No previous release found, retrieving all commits
ℹ  Found 132 commits since last release
ℹ  There is no previous release, the next release version is 1.0.0
✔  Published release 1.0.0 on default channel

semantic-release's get-next-version.js hardcodes FIRST_RELEASE = "1.0.0" when no prior tag exists — this is the literal constant, the analyzer's bump type is ignored on first release. So the merge produces v1.0.0 (not v1.0.1), with a CHANGELOG covering all 14 historical feat:/fix:/refactor: commits since project inception (the 118 chore:/docs:/ci:/test:/style:/perf:/merge commits are filtered out by the preset config).

Required follow-up before merge

These belong on Packagist + GitHub repo settings, not in this PR:

1. On Packagist (logged in as the team account): Profile → Show API Token → copy.
2. In the GitHub repo: Settings → Secrets and variables → Actions add PACKAGIST_USERNAME and PACKAGIST_API_TOKEN.
3. Skip the "Connect your user account to GitHub" prompt on Packagist — not used by this flow.
4. (Already done out-of-band) Stale merged branches were deleted from origin so Packagist's "package cannot require itself" freeze cleared.

Test plan

• Configure PACKAGIST_USERNAME and PACKAGIST_API_TOKEN repo secrets.
• Merge this PR and verify:
  • Quality Checks workflow runs and succeeds on main.
  • Release workflow now fires on the workflow_run (it has never fired before this PR).
  • semantic-release emits v1.0.0, generates CHANGELOG.md, commits with [skip ci], pushes the tag.
  • Notify Packagist of new release step reports Notifying Packagist of release v1.0.0 and exits 0.
  • convertcom/php-sdk v1.0.0 appears on Packagist within ~1 min.
  • composer require convertcom/php-sdk resolves to 1.0.0 from a clean test directory.

🤖 Generated with Claude Code

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1214285553251178

[gemini-code-assist]

Code Review

This pull request updates the RELEASE.md documentation to reflect a transition from using Packagist webhooks to a release workflow that utilizes Packagist's /api/update-package endpoint. The changes include updated step-by-step instructions for configuring Packagist API tokens and GitHub secrets, as well as an updated setup checklist. I have no feedback to provide.