# Automatic Fluid Theme Update Workflows

Every Fluid site pins an exact version of `@fluid-theme/core` (never a live runtime CDN link) and receives automatic pull requests when a new version is published to public npm.

No npm token or repository secret is required because `@fluid-theme/core` is public on npm (`https://www.npmjs.com/package/@fluid-theme/core`). GitHub's built-in `GITHUB_TOKEN` opens the update pull request.

## Which one a site uses

| Site | Tool | Why |
|---|---|---|
| `@fluid-theme/core` in `package.json` (copies `dist/` at build) | `dependabot.yml` | Dependabot's PRs run the site's own checks and cost no Actions minutes until CI runs |
| CSS vendored in the repo, no npm dependency | `update-fluid-theme.yml` | Dependabot cannot see vendored files |

Use one per site, never both: the workflow skips any site whose `package.json` lists `@fluid-theme/core`, so a bump never opens two PRs.

## 1. Vendored sites: copy the workflow

Copy `update-fluid-theme.yml` into your site repository at:

```text
.github/workflows/update-fluid-theme.yml
```

Also ensure **Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests** is ticked in the site repository (off by default in an organization; set it at the org level for every site at once).

**CI on the update PR.** A pull request opened with the built-in `GITHUB_TOKEN` does not trigger the site's `pull_request` workflows, so it shows no checks and an agent cannot "merge when green". Add a repository or organization secret `FLUID_UPDATE_TOKEN` (a GitHub App installation token or a fine-grained token with contents and pull-requests write); the workflow uses it when present. Without it, close and reopen the PR to run checks.

**Cost.** Each run takes about a minute of Actions time in the site's account (weekly: about 4-5 minutes a month per site). Organizations near their monthly cap can drop the `schedule:` trigger and run it by hand.

### How it works

1. Runs every Monday (`09:17 UTC`) and on manual **Run workflow** (`workflow_dispatch`).
2. Reads the site's current version from the first-line banner of the vendored `fluid.min.css` (`/* @fluid-theme/core vX.Y.Z | ... */`). A site whose `package.json` lists `@fluid-theme/core` is skipped: Dependabot updates it.
3. Checks `npm view @fluid-theme/core version` on public npm.
4. **Holds major upgrades by default:** if a new major version is out (for example `2.x` → `3.x`), weekly runs stay within the current major line and log a notice in the Actions summary. Trigger the workflow manually with `allow_major: true` when you are ready to adopt a major upgrade.
5. Refreshes the vendored `fluid*.min.css`, `fonts/`, `swiss.css` / `gallery.css` child themes, and `toc.js` / `fit-text.js` files already present in the site (it never adds new files and never runs the site's build), commits only those files, and opens or updates a single pull request on the branch `chore/fluid-theme-update` (a newer release updates the open PR rather than opening a second).

## 2. `package.json` sites: Dependabot

Sites that install `@fluid-theme/core` in `package.json` and copy `node_modules/@fluid-theme/core/dist/` during `npm run build` copy `dependabot.yml` to `.github/dependabot.yml` (not the workflow). It groups `@fluid-theme/*` updates weekly and ignores major version jumps until an intentional migration.