From 185f89cdd087b8e4a36dedd4a901bc074f5f023d Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 10 Feb 2026 12:03:21 -0500 Subject: [PATCH 1/5] docs: Describe publishing --- PUBLISHING.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 PUBLISHING.md diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..aca4315 --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,62 @@ +# NPM Trusted Publishing & Provenance + +This document outlines how to enable NPM trusted publishing and provenance for HarperFast repositories. This allows for more secure publishing eliminating the need for long-lived NPM tokens in GitHub Secrets. + +## 1. Update GitHub Release Workflow + +Add the following permissions to your GitHub release workflow (usually in `.github/workflows/release.yaml`). These are required for `semantic-release` to create GitHub releases and publish to NPM. + +```yaml +permissions: + contents: write + issues: write + pull-requests: write + id-token: write +``` + +> **Note:** The `id-token: write` permission is specifically required for NPM provenance and trusted publishing. + +### Adjust the Publish Step + +Update your NPM publish step to include the `--provenance` flag: + +```yaml +- name: Publish to NPM + run: npm publish --provenance +``` + +## 2. Initial Manual Publication + +If the package has never been published to NPM before, you must manually publish it once from your local machine. + +For `@harperfast` scoped packages, use: + +```bash +npm publish --access public +``` + +This initial manual publish adds the package to NPM, allowing you to then configure it for trusted publishing. + +## 3. Configure NPM Trusted Publisher + +Once the package exists on NPM, you can configure the repository as a trusted publisher: + +1. Visit `https://www.npmjs.com/package/{packageName}/access` +2. Add or edit a **Trusted Publisher**. +3. **Publisher:** GitHub Actions +4. **Organization or user:** `HarperFast` (or the appropriate owner) +5. **Repo:** The exact name of your repository. +6. **Workflow filename:** The exact name of your release workflow file (e.g., `release.yaml`). This is case-sensitive and must be located in the `.github/workflows/` folder. +7. **Environment name:** Leave blank unless you are specifically using GitHub Environments. + +## 4. Restrict Publishing Access + +While you're in NPM access settings, also disallow tokens: + +> Require two-factor authentication and disallow tokens (recommended) + +Remember to hit save! + +## Example + +For a reference implementation, see the [hairper release workflow](https://github.com/HarperFast/hairper/blob/main/.github/workflows/release.yaml). From 520757e39f7f9aa47f3819ca05d7bb26440402b9 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 10 Feb 2026 12:10:20 -0500 Subject: [PATCH 2/5] docs: Talk about semantic release too --- PUBLISHING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/PUBLISHING.md b/PUBLISHING.md index aca4315..8153c44 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -57,6 +57,78 @@ While you're in NPM access settings, also disallow tokens: Remember to hit save! +## 5. Using Semantic Release (Optional) + +HarperFast projects often use `semantic-release` to automate the entire package release workflow, including determining the next version number, generating release notes, and publishing to NPM. + +### Configuration + +You can configure `semantic-release` using a `.releaserc.json` file or a `release.config.js` file in your repository root. + +**Example `.releaserc.json`:** + +```json +{ + "branches": ["main"], + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + ["@semantic-release/npm", {"npmPublish": false}], + "@semantic-release/github" + ] +} +``` + +### Required Dependencies + +Ensure you have the following devDependencies in your `package.json`: + +```bash +npm install --save-dev semantic-release @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/github +``` + +### GitHub Actions Integration + +When using `semantic-release`, your publish step in GitHub Actions might look like this: + +```yaml +jobs: + release: + name: Release + environment: Release + # Ensure releases run only when code reaches main via GitHub Merge Queue, or when manually dispatched + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + fetch-depth: 0 + - name: Setup Node.js + uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0 + with: + node-version-file: '.nvmrc' + cache: npm + registry-url: 'https://registry.npmjs.org' + - name: Update npm + run: npm install -g npm@latest + - name: Install dependencies + run: npm ci + - name: Check lint + run: npm run lint + - name: Check format + run: npm run format + - name: Run unit tests + run: npm test + - name: Semantic Release + if: ${{ github.event_name == 'push' }} + uses: cycjimmy/semantic-release-action@b12c8f6015dc215fe37bc154d4ad456dd3833c90 # v6.0.0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NPM_CONFIG_PROVENANCE: true + - name: Publish to NPM + run: npm publish --provenance +``` + ## Example For a reference implementation, see the [hairper release workflow](https://github.com/HarperFast/hairper/blob/main/.github/workflows/release.yaml). From 38bbaf1857033d5dd1400797780301fdb8f6854e Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 10 Feb 2026 12:42:26 -0500 Subject: [PATCH 3/5] docs: Always specify HarperFast as the desired org Co-authored-by: Ethan Arrowood --- PUBLISHING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PUBLISHING.md b/PUBLISHING.md index 8153c44..a48833d 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -44,7 +44,7 @@ Once the package exists on NPM, you can configure the repository as a trusted pu 1. Visit `https://www.npmjs.com/package/{packageName}/access` 2. Add or edit a **Trusted Publisher**. 3. **Publisher:** GitHub Actions -4. **Organization or user:** `HarperFast` (or the appropriate owner) +4. **Organization or user:** `HarperFast` 5. **Repo:** The exact name of your repository. 6. **Workflow filename:** The exact name of your release workflow file (e.g., `release.yaml`). This is case-sensitive and must be located in the `.github/workflows/` folder. 7. **Environment name:** Leave blank unless you are specifically using GitHub Environments. From 9f64c23605bfda911bbff43a2af8ea56ca7a0950 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 10 Feb 2026 12:44:07 -0500 Subject: [PATCH 4/5] docs: Lowercase npm --- PUBLISHING.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/PUBLISHING.md b/PUBLISHING.md index a48833d..7ae2f97 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -1,10 +1,10 @@ -# NPM Trusted Publishing & Provenance +# npm Trusted Publishing & Provenance -This document outlines how to enable NPM trusted publishing and provenance for HarperFast repositories. This allows for more secure publishing eliminating the need for long-lived NPM tokens in GitHub Secrets. +This document outlines how to enable npm trusted publishing and provenance for HarperFast repositories. This allows for more secure publishing eliminating the need for long-lived npm tokens in GitHub Secrets. ## 1. Update GitHub Release Workflow -Add the following permissions to your GitHub release workflow (usually in `.github/workflows/release.yaml`). These are required for `semantic-release` to create GitHub releases and publish to NPM. +Add the following permissions to your GitHub release workflow (usually in `.github/workflows/release.yaml`). These are required for `semantic-release` to create GitHub releases and publish to npm. ```yaml permissions: @@ -14,20 +14,20 @@ permissions: id-token: write ``` -> **Note:** The `id-token: write` permission is specifically required for NPM provenance and trusted publishing. +> **Note:** The `id-token: write` permission is specifically required for npm provenance and trusted publishing. ### Adjust the Publish Step -Update your NPM publish step to include the `--provenance` flag: +Update your npm publish step to include the `--provenance` flag: ```yaml -- name: Publish to NPM +- name: Publish to npm run: npm publish --provenance ``` ## 2. Initial Manual Publication -If the package has never been published to NPM before, you must manually publish it once from your local machine. +If the package has never been published to npm before, you must manually publish it once from your local machine. For `@harperfast` scoped packages, use: @@ -35,11 +35,11 @@ For `@harperfast` scoped packages, use: npm publish --access public ``` -This initial manual publish adds the package to NPM, allowing you to then configure it for trusted publishing. +This initial manual publish adds the package to npm, allowing you to then configure it for trusted publishing. -## 3. Configure NPM Trusted Publisher +## 3. Configure npm Trusted Publisher -Once the package exists on NPM, you can configure the repository as a trusted publisher: +Once the package exists on npm, you can configure the repository as a trusted publisher: 1. Visit `https://www.npmjs.com/package/{packageName}/access` 2. Add or edit a **Trusted Publisher**. @@ -51,7 +51,7 @@ Once the package exists on NPM, you can configure the repository as a trusted pu ## 4. Restrict Publishing Access -While you're in NPM access settings, also disallow tokens: +While you're in npm access settings, also disallow tokens: > Require two-factor authentication and disallow tokens (recommended) @@ -59,7 +59,7 @@ Remember to hit save! ## 5. Using Semantic Release (Optional) -HarperFast projects often use `semantic-release` to automate the entire package release workflow, including determining the next version number, generating release notes, and publishing to NPM. +HarperFast projects often use `semantic-release` to automate the entire package release workflow, including determining the next version number, generating release notes, and publishing to npm. ### Configuration @@ -125,7 +125,7 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_CONFIG_PROVENANCE: true - - name: Publish to NPM + - name: Publish to npm run: npm publish --provenance ``` From 45969b6f65d78cb36eae3180f2f0c24aa47359b0 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 17 Feb 2026 16:34:30 -0500 Subject: [PATCH 5/5] docs: Clarify manual vs semantic release --- PUBLISHING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/PUBLISHING.md b/PUBLISHING.md index 7ae2f97..e399d77 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -4,7 +4,7 @@ This document outlines how to enable npm trusted publishing and provenance for H ## 1. Update GitHub Release Workflow -Add the following permissions to your GitHub release workflow (usually in `.github/workflows/release.yaml`). These are required for `semantic-release` to create GitHub releases and publish to npm. +Add the following permissions to your GitHub release workflow (usually in `.github/workflows/release.yaml`). These are required to properly allow the workflow to create GitHub releases and publish to npm. ```yaml permissions: @@ -57,11 +57,16 @@ While you're in npm access settings, also disallow tokens: Remember to hit save! -## 5. Using Semantic Release (Optional) +## 5. Increment your package versions + +I'll mention two options for configuring version increments: + +- **Manual Increment:** Manually update the version number in your `package.json` file before publishing. +- **Automated Increment with Semantic Release:** Use `semantic-release` to automatically determine and update the version number based on commit messages. HarperFast projects often use `semantic-release` to automate the entire package release workflow, including determining the next version number, generating release notes, and publishing to npm. -### Configuration +### Semantic Release Configuration You can configure `semantic-release` using a `.releaserc.json` file or a `release.config.js` file in your repository root. @@ -131,4 +136,4 @@ jobs: ## Example -For a reference implementation, see the [hairper release workflow](https://github.com/HarperFast/hairper/blob/main/.github/workflows/release.yaml). +For a reference implementation, see the [harper-agent release workflow](https://github.com/HarperFast/harper-agent/blob/main/.github/workflows/release.yaml).