ci(release): add cloudsmith publish workflow for fetch-with-retries

Adds the release-only plumbing needed to publish the `fetch-with-retries` package
from CircleCI to FT’s private Cloudsmith npm registry. I’ve already
tested this with a pre-release (v0.1.0) and it worked fine, and have
imported it successfully into a local clone of one of our other repos,
for testing.

The publishing workflow is tag-gated, package-scoped, and publishes via
`npm publish --workspace packages/fetch-with-retries`.

This repo uses Cloudsmith rather than public npm because the package is intended
for internal use, and should not be published publicly.

Author: leafrogers

.circleci/config.yml

@@ -1,6 +1,7 @@
 version: 2.1
 
 orbs:
+  cloudsmith-npm: ft-circleci-orbs/cloudsmith-npm@1.0
   node: circleci/node@4.6.0
 
 references:
@@ -19,6 +20,18 @@ references:
     attach_workspace:
       at: *workspace_root
 
+  filters_release_build: &filters_release_build
+    tags:
+      only:
+        # Although the CI setup here is mostly from dotcom-reliability-kit,
+        # we’re simplifying this tagging filter for now while we only have one
+        # package. The dotcom kit uses \w instead of hard-coding the package
+        # name, then runs a script (circleci-publish.sh) to figure out which
+        # package to publish. We could adopt that later if we like!
+        - /^fetch-with-retries-v\d+\.\d+\.\d+$/
+    branches:
+      ignore: /.*/
+
 jobs:
   install:
     <<: *container_config_node
@@ -50,6 +63,16 @@ jobs:
           name: Run repo linting
           command: npm run lint
 
+  publish:
+    <<: *container_config_node
+    steps:
+      - *attach_workspace
+      - cloudsmith-npm/configure_npm:
+          repository: financial-times-internal-releases
+      - run:
+          name: Publish fetch-with-retries to Cloudsmith
+          command: npm publish --workspace packages/fetch-with-retries
+
 workflows:
   test-and-lint:
     jobs:
@@ -69,3 +92,33 @@ workflows:
           name: lint-v24.15
           requires:
             - install-v24.15
+  publish:
+    jobs:
+      - install:
+          filters:
+            <<: *filters_release_build
+          name: install-publish-v<< matrix.node-version >>
+          matrix:
+            parameters:
+              node-version: ["26.2", "24.15", "22.22"]
+      - test:
+          filters:
+            <<: *filters_release_build
+          name: test-publish-v<< matrix.node-version >>
+          requires:
+            - install-publish-v<< matrix.node-version >>
+          matrix:
+            parameters:
+              node-version: ["26.2", "24.15", "22.22"]
+      - lint:
+          filters:
+            <<: *filters_release_build
+          name: lint-publish-v24.15
+          requires:
+            - install-publish-v24.15
+      - publish:
+          filters:
+            <<: *filters_release_build
+          requires:
+            - test-publish-v24.15
+            - lint-publish-v24.15

README.md

@@ -37,25 +37,24 @@ npm run test -w packages/fetch-with-retries
 
 ## Publishing
 
-`packages/fetch-with-retries` is configured to publish to Cloudsmith from CircleCI.
+Packages (e.g. `packages/fetch-with-retries`) are configured to publish from CircleCI to Cloudsmith after creating a GitHub release.
 
-CircleCI project settings must include:
+Publishing flow:
 
-```bash
-CLOUDSMITH_SERVICE_ACCOUNT=<your-service-account-id>
-```
+1. Update the package version, e.g. `packages/fetch-with-retries/package.json`.
+2. Update the CHANGELOG for that version, e.g. `packages/fetch-with-retries/CHANGELOG.md`.
+3. Open a PR to get those changes merged into the main branch.
+4. When merged, create a GitHub release targeting the release commit, and use a matching tag in this format:
 
-The publish workflow is triggered by tags in this format:
-
-```bash
+```
 fetch-with-retries-v1.0.0
 ```
 
-Publishing is package-scoped and runs:
+5. CircleCI will run the publish workflow for that tag.
+6. If tests and lint pass, CircleCI publishes the package to the `financial-times-internal-releases` Cloudsmith repository.
 
-```bash
-npm publish --workspace packages/fetch-with-retries
-```
+> [!IMPORTANT]
+> The tag version must match the package version in your `package.json`. The CircleCI workflow is triggered by the git tag itself, not by a GitHub release title.
 
 ## Contact
 

packages/fetch-with-retries/README.md

@@ -12,6 +12,7 @@ Retry native Node `fetch` calls with a shared default policy, configurable backo
     - [`options.retryPatchRequests`](#optionsretrypatchrequests)
   - [Structured log events](#structured-log-events)
   - [TypeScript](#typescript)
+  - [Publishing](#publishing)
 - [License](#license)
 
 ## Usage
@@ -184,6 +185,25 @@ Retries exhausted event:
 }
 ```
 
+### Publishing
+
+Maintainers publish this package through CircleCI rather than from a local machine.
+
+1. Update the version in `package.json`.
+2. Update `CHANGELOG.md` for that version.
+3. Open a PR to get those changes merged into the main branch.
+4. When merged, create a GitHub release targeting the release commit, and use a matching tag:
+
+```
+fetch-with-retries-v1.0.0
+```
+
+5. CircleCI will run the tagged publish workflow.
+6. If tests and lint pass, CircleCI publishes `@financial-times/martech-fetch-with-retries` to the `financial-times-internal-releases` Cloudsmith repository.
+
+> [!IMPORTANT]
+> The tag version must match the package version in `package.json`. The CircleCI workflow is triggered by the git tag itself, not by a GitHub release title.
+
 ## License
 
 MIT