ci: tell the documentation site when a release reaches public npm - #18
ci: tell the documentation site when a release reaches public npm#18ArtemKosolap wants to merge 1 commit into
Conversation
The site advertises a version and a command surface, and nothing told it when either changed. It fell a whole release behind in a single day once, because the page was corrected the day before this CLI's self-update command shipped. Triggered by the completion of publish-public, which is the moment a version becomes public: it publishes to npm and then flips the tag's Release to latest. The release event is deliberately not used — that flip runs with the default GITHUB_TOKEN, and events it raises do not start other workflows. The version is read back from the registry rather than taken from the run's inputs. What the site has to advertise is what `npm install -g reply-cli` actually fetches, and only the registry knows that; this repository's package.json is 0.0.0-development by design. This sends a notification and nothing else. It cannot edit the site, and the site publishes nothing without a human merging a pull request there. The target repository comes from a variable and the credential from a secret; with either missing the job warns and succeeds.
|
Closing unmerged. The site now reads these facts itself on a schedule, so no notification is needed here — and, more importantly, the push model required a credential with write access to another repository to live in this repository's secrets. Reading public sources needs no credential at all, so this repository is better off holding none. |
|
Closing without merging — we've decided against a push trigger here. This workflow needs a token with write access to the documentation site's repository, stored in this repository's secrets. This repository is public, and anyone with write access to a public repository can push a workflow that prints a secret into a run log. That would make the token readable by everyone with commit rights here, while granting write access somewhere else. The convenience isn't worth that. The site polls instead. It reads the published version from the npm registry and cross-checks the release tag, both anonymously, so no credential is needed on either side — nothing to provision here, nothing to rotate, nothing to leak. The trade is latency: the site can be up to a day behind a release rather than minutes. That's fine for a package that ships ad hoc with no dated announcement. No action needed in this repository. |
1 participant
What
A workflow that fires a
repository_dispatchat the documentation site once a version is live onpublic npm, so the site can check its own
/clipage and open a pull request against it.The trigger, and one that looks better but does not work
It runs on the completion of
publish-public, which is the moment a version becomes public:that workflow publishes to npm and then flips the tag's GitHub Release to latest.
The obvious alternative —
on: release: types: [released]— is deliberately not used. That flip isperformed with the default
GITHUB_TOKEN, and events raised by it do not start other workflows. Itwould look correct and silently never fire.
A failed or cancelled promotion changed nothing public, so the job is skipped unless the run
succeeded.
The version comes from the registry
Not from the run's inputs, and not from this repository. What the site has to advertise is what a
reader's
npm install -g reply-cliactually fetches, and only the registry knows that. Thisrepository's
package.jsonstays0.0.0-developmentby design — semantic-release stamps the realversion at publish time — so it is never a source for anything the site says.
What it can and cannot do
It sends a notification. That is the whole job. It cannot edit the site, and the site publishes
nothing without a human merging a pull request there. If the notification never arrives, the site
re-checks on a schedule regardless — so this shortens the delay from days to minutes rather than
being the only line of defence.
Worth having, because the page fell a whole release behind in a single day: it was corrected the day
before
reply installshipped.Configuration
Two settings, both optional, both needed for the fast path:
SITE_SYNC_REPOowner/nameof the site repository to notifySITE_SYNC_TOKENcontents: read/writeon that repositoryA repository's own
GITHUB_TOKENcannot dispatch across repositories, which is the only reason aseparate credential is involved.
With either missing the job warns and succeeds. A documentation notification must never be able
to fail a build, and this one is merge-safe before anything is configured.
The target repository is read from a variable rather than written into this file: this repository is
public and the site's is not, so hardcoding the name here would publish it.
Not touched
publish-public.ymlis left exactly as it is. Its filename and environment name are fixed by thenpm trusted-publisher configuration, and its OIDC setup is delicate enough that adding a step to it
to save a file was not worth the risk.
Verification
steps:well-formed, dispatch typecli-released.workflow_runonly onsuccess.