mirror of
https://github.com/Novaloop-AG/healthchat-web.git
synced 2026-11-04 01:19:41 +00:00
chore(release): set up tag-driven HealthChat release pipeline
Convert build-healthchat workflow from branch-push to tag-push trigger (healthchat-v*), add version/workspace-ref/release-notes resolution, and create a GitHub Release on tag push. Pin healthchat-workspace to v0.5.0-rc.4 via .healthchat-workspace-version, seed the changelog with 1.0.0, and document the runbook in the releasing-healthchat skill.
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: releasing-healthchat
|
||||
description: Cut a versioned HealthChat release of element-web by tagging release/healthchat. Use when the user asks to release, publish, tag, or cut a new HealthChat version, or asks about the release/deployment process for HealthChat element-web.
|
||||
---
|
||||
|
||||
# Releasing HealthChat (element-web)
|
||||
|
||||
Releases are driven by git tags of the form `healthchat-v<semver>` pushed to
|
||||
`origin`. The tag triggers `.github/workflows/build-healthchat.yaml`, which
|
||||
builds the HealthChat Docker image, publishes it to ghcr.io under
|
||||
`healthchat-web:<version>`, `:stable`, and `:<sha>`, and creates a GitHub
|
||||
Release whose body is the matching section of `HEALTHCHAT_CHANGES.md`.
|
||||
|
||||
Publish target: **ghcr.io Docker image + GitHub Release only.** No npm,
|
||||
no tarball distribution, no desktop/mobile fan-out.
|
||||
|
||||
## Preflight checklist
|
||||
|
||||
Verify each item before tagging. If any fail, fix and commit first.
|
||||
|
||||
- [ ] On branch `release/healthchat` with a clean working tree (`git status`).
|
||||
- [ ] `HEALTHCHAT_CHANGES.md` has a section `## Changes in <new-version> (<date>)`
|
||||
at the top of the file. The pipeline's awk extractor matches this exact
|
||||
heading format.
|
||||
- [ ] `.healthchat-workspace-version` points at the healthchat-workspace tag
|
||||
or ref that should ship with this release. Bump it in the same commit
|
||||
as the changelog entry if needed.
|
||||
- [ ] `package.json` version can optionally be bumped to match (cosmetic —
|
||||
the git tag is the source of truth for the build).
|
||||
- [ ] No uncommitted changes to `.github/workflows/build-healthchat.yaml`,
|
||||
`Dockerfile`, or `docker/` that haven't been manually sanity-checked.
|
||||
|
||||
## Cutting the release (normal path)
|
||||
|
||||
```bash
|
||||
# from release/healthchat, fully committed:
|
||||
git tag healthchat-v<MAJOR>.<MINOR>.<PATCH>
|
||||
git push origin healthchat-v<MAJOR>.<MINOR>.<PATCH>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `git tag healthchat-v1.0.0`
|
||||
- `git tag healthchat-v1.4.0-rc1`
|
||||
- `git tag healthchat-v1.4.0-hotfix1`
|
||||
|
||||
The workflow triggers automatically. Watch it via `gh run watch` or GitHub
|
||||
Actions UI.
|
||||
|
||||
## Manual / retry path (workflow_dispatch)
|
||||
|
||||
Use when retrying a failed run, testing the pipeline, or rebuilding an image
|
||||
without moving tags.
|
||||
|
||||
1. GitHub → Actions → "Release HealthChat" → **Run workflow**.
|
||||
2. Fill in:
|
||||
- **version** (required): e.g. `1.4.0`. Same regex validation as tag path.
|
||||
- **workspace_ref** (optional): overrides `.healthchat-workspace-version`.
|
||||
- **release_notes_override** (optional): replaces the `HEALTHCHAT_CHANGES.md`
|
||||
lookup.
|
||||
3. Run. Docker image is pushed. **No GitHub Release is created on the dispatch
|
||||
path** — only the tag-push path creates Releases (keeps manual retries from
|
||||
clobbering the release history).
|
||||
|
||||
## Tag format
|
||||
|
||||
```
|
||||
healthchat-v<MAJOR>.<MINOR>.<PATCH>[-<suffix>]
|
||||
```
|
||||
|
||||
Suffix conventions (informational; regex accepts any
|
||||
`[0-9A-Za-z.-]+`):
|
||||
|
||||
- `-rc1`, `-rc2` — release candidates
|
||||
- `-hotfix1` — post-release fixes on an existing minor
|
||||
- `-dryrun1`, `-renew-test` — one-off pipeline tests
|
||||
|
||||
The `healthchat-` prefix keeps these tags distinct from upstream
|
||||
element-hq `v<semver>` tags if they are ever fetched into the repo.
|
||||
|
||||
Regex used for validation (must match):
|
||||
`^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$`
|
||||
|
||||
## Release notes
|
||||
|
||||
`HEALTHCHAT_CHANGES.md` is the single source. The workflow extracts the
|
||||
section matching the version being released. Format:
|
||||
|
||||
```markdown
|
||||
## Changes in 1.4.0 (2026-04-21)
|
||||
|
||||
Short summary line (optional).
|
||||
|
||||
🙌 Improvements
|
||||
|
||||
- Bullet one.
|
||||
- Bullet two.
|
||||
```
|
||||
|
||||
If no matching section exists, the pipeline falls back to
|
||||
`HealthChat <version> — automated build from <ref>.` and emits a workflow
|
||||
warning. Prefer fixing the changelog over relying on the fallback.
|
||||
|
||||
## After the release
|
||||
|
||||
- [ ] Workflow run is green in GitHub Actions.
|
||||
- [ ] `docker pull ghcr.io/<owner>/healthchat-web:<version>` succeeds.
|
||||
- [ ] GitHub Release exists at
|
||||
`https://github.com/<owner>/<repo>/releases/tag/healthchat-v<version>`
|
||||
with the correct body.
|
||||
- [ ] The `:stable` tag on ghcr.io now points at the new digest
|
||||
(`docker buildx imagetools inspect ghcr.io/<owner>/healthchat-web:stable`).
|
||||
|
||||
## Required secrets
|
||||
|
||||
Configured in repo Settings → Secrets and variables → Actions:
|
||||
|
||||
| Secret | Purpose |
|
||||
|---|---|
|
||||
| `HEALTHCHAT_WORKSPACE_TOKEN` | PAT with read access to `Novaloop-AG/healthchat-workspace`. Needed by `actions/checkout` for the private plugin repo. |
|
||||
| `GITHUB_TOKEN` | Auto-provided. Used for ghcr.io login and GitHub Release creation. No manual setup required. |
|
||||
|
||||
## Rollback
|
||||
|
||||
- **Bad image, notes fine** → fix the cause, commit, tag `healthchat-v<ver>-hotfix1`.
|
||||
- **Bad release notes** → edit `HEALTHCHAT_CHANGES.md` and the GitHub Release
|
||||
body manually (GitHub UI). The ghcr.io tag is immutable, don't try to move it.
|
||||
- **Completely wrong tag** → delete the GitHub Release (UI). Do **not** delete
|
||||
the ghcr.io image tag — treat it as burned. Re-tag with a new version.
|
||||
|
||||
## Known branch divergence on rebase
|
||||
|
||||
These files are HealthChat-only and will conflict cleanly when rebasing
|
||||
`release/healthchat` onto upstream. Always keep the HealthChat side (`--ours`
|
||||
during rebase):
|
||||
|
||||
- `.github/workflows/build-healthchat.yaml`
|
||||
- `HEALTHCHAT_CHANGES.md`
|
||||
- `.healthchat-workspace-version`
|
||||
- `.claude/skills/releasing-healthchat/SKILL.md`
|
||||
Reference in New Issue
Block a user