# Coda Sync Setup

## How sync runs

Coda sync runs automatically as a `sync-coda` job chained inside `.github/workflows/release.yml`
on every `v*` tag push. It runs after the `release` job (zip build + GitHub release creation)
succeeds, in the same workflow run.

**Why it's chained instead of triggered by `release: published`:**
GitHub's recursion guard prevents workflows triggered by `GITHUB_TOKEN` from firing other
workflows via cross-workflow events. Because `release.yml` creates the GitHub release with the
default `GITHUB_TOKEN`, the `release: published` event in `sync-coda-version.yml` never fires
for real releases — only manual `workflow_dispatch` runs worked. The fix chains the Coda sync
directly in `release.yml` so it runs in the same workflow context, bypassing the recursion guard.

## Manual re-sync (fallback)

`sync-coda-version.yml` retains a `workflow_dispatch` trigger for manual re-syncs by tag
(e.g. if the automatic run failed or you need to re-push a specific version to Coda):

1. Go to the repository `Actions` tab.
2. Select `Sync Coda Version`.
3. Click `Run workflow`, enter the tag (e.g. `v7.26.2`), and run.

The `release: published` trigger in `sync-coda-version.yml` is kept but will not fire for
GITHUB_TOKEN-created releases — the chained job in `release.yml` is the authoritative sync path.

## Add `CODA_API_TOKEN` to GitHub

1. Open the GitHub repository.
2. Go to `Settings` -> `Secrets and variables` -> `Actions`.
3. Click `New repository secret`.
4. Set the name to `CODA_API_TOKEN`.
5. Paste the Coda API token value.
6. Save the secret.

If the secret is absent, the `sync-coda` job logs a warning and exits cleanly (no failure).

## Validate

- Push a `v*` tag. Confirm the `Release` workflow runs both the `release` job and the
  `sync-coda` job successfully.
- Verify the target Coda page updates with the released version and ZIP link.
