Update environment configuration in releases.yml

chore(deps-dev): bump picomatch from 2.3.1 to 2.3.2

.github/CONTRIBUTING.md

@@ -57,3 +57,8 @@ This will ask you some questions about the new package. Start with `0.0.0` as th
 ```
 
 3. Start developing 😄.
+
+## Releasing Packages
+
+For information on how packages are published to npm, including workflow inputs, dist-tags, and safety guards, see the [release documentation](../docs/release.md).
+

.github/workflows/releases.yml

@@ -1,6 +1,6 @@
 name: Publish NPM
 
-run-name: Publish NPM - ${{ github.event.inputs.package }}
+run-name: Publish NPM - ${{ inputs.package }} from ${{ inputs.branch }}
 
 on:
   workflow_dispatch:
@@ -20,7 +20,21 @@ on:
           - http-client
           - io
           - tool-cache
-          
+      branch:
+        type: string
+        required: false
+        default: 'main'
+        description: 'Branch to release from'
+      npm-tag:
+        type: string
+        required: false
+        default: 'latest'
+        description: 'npm dist-tag for the release. Use "latest" for main branch releases. For non-main branches, use a non-semver tag like "v1-longlived". Semver values (e.g. "5.0.0") are not valid dist-tags and will be rejected by npm.'
+      test-all:
+        type: boolean
+        required: false
+        default: false
+        description: 'Run tests for all packages instead of only the package being published'
 
 jobs:
   test:
@@ -28,13 +42,15 @@ jobs:
 
     steps:
       - name: setup repo
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.branch }}
 
       - name: verify package exists
         run: ls packages/${{ github.event.inputs.package }}
 
       - name: Set Node.js 24.x
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: 24.x
 
@@ -48,14 +64,19 @@ jobs:
         run: npm run build
 
       - name: test
-        run: npm run test
+        run: |
+          if [ "${{ inputs.test-all }}" = "true" ]; then
+            npm run test
+          else
+            npm run test -- --testPathPattern="packages/${{ inputs.package }}"
+          fi
 
       - name: pack
         run: npm pack
         working-directory: packages/${{ github.event.inputs.package }}
 
       - name: upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ github.event.inputs.package }}
           path: packages/${{ github.event.inputs.package }}/*.tgz
@@ -63,36 +84,44 @@ jobs:
   publish:
     runs-on: ubuntu-slim
     needs: test
-    environment: npm-publish
+    environment:
+      name: npm-publish
+      deployment: false
     permissions:
       contents: read
       id-token: write
     steps:
 
       - name: Set Node.js 24.x
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: 24.x
 
       - name: download artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
-          name: ${{ github.event.inputs.package }}
+          name: ${{ inputs.package }}
+
+      - name: guard against publishing latest from non-main branch
+        if: inputs.branch != 'main' && inputs.npm-tag == 'latest'
+        run: |
+          echo "::error::Publishing with the 'latest' dist-tag from a non-main branch ('${{ inputs.branch }}') is not allowed. Use the package major version as the tag (e.g. v5)."
+          exit 1
 
       - name: publish
-        run: npm publish --provenance *.tgz
+        run: npm publish --provenance --tag "${{ inputs.npm-tag }}" *.tgz
 
       - name: notify slack on failure
         if: failure()
         run: |
-          curl -X POST -H 'Content-type: application/json' --data '{"text":":pb__failed: Failed to publish a new version of ${{ github.event.inputs.package }}"}' $SLACK_WEBHOOK
+          curl -X POST -H 'Content-type: application/json' --data '{"text":":pb__failed: Failed to publish a new version of ${{ inputs.package }} from ${{ inputs.branch }} (tag: ${{ inputs.npm-tag }})"}' $SLACK_WEBHOOK
         env:
           SLACK_WEBHOOK: ${{ secrets.SLACK }}
 
       - name: notify slack on success
         if: success()
         run: |
-          curl -X POST -H 'Content-type: application/json' --data '{"text":":dance: Successfully published a new version of ${{ github.event.inputs.package }}"}' $SLACK_WEBHOOK
+          curl -X POST -H 'Content-type: application/json' --data '{"text":":dance: Successfully published a new version of ${{ inputs.package }} from ${{ inputs.branch }} (tag: ${{ inputs.npm-tag }})"}' $SLACK_WEBHOOK
         env:
           SLACK_WEBHOOK: ${{ secrets.SLACK }}
 

docs/release.md

@@ -0,0 +1,82 @@
+# Releasing Packages
+
+Packages are published to npm via the **Publish NPM** workflow ([`.github/workflows/releases.yml`](../.github/workflows/releases.yml)). The workflow is triggered manually through `workflow_dispatch` from the GitHub Actions UI.
+
+## How it works
+
+The workflow has two jobs:
+
+1. **test** — Checks out the specified branch, installs dependencies, bootstraps the monorepo, builds all packages, runs tests, then packs the target package into a `.tgz` archive and uploads it as a workflow artifact.
+2. **publish** — Downloads the packed artifact and publishes it to npm with `--provenance` (OIDC-based). Sends a Slack notification on success or failure. Requires the `npm-publish` environment.
+
+## Inputs
+
+| Input | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `package` | choice | **yes** | — | Which package to release. One of: `artifact`, `attest`, `cache`, `core`, `exec`, `github`, `glob`, `http-client`, `io`, `tool-cache`. |
+| `branch` | string | no | `main` | The branch to check out and release from. |
+| `npm-tag` | string | no | `latest` | The npm dist-tag to publish under. See [Dist-tags](#dist-tags) below. |
+| `test-all` | boolean | no | `false` | When `false`, only tests for the selected package are run. Set to `true` to run the full test suite across all packages. |
+
+## Dist-tags
+
+npm dist-tags control which version users get when they `npm install @actions/<package>` (or `@<tag>`).
+
+> **Important:** npm dist-tags **cannot** be valid semver strings. Values like `5.0.0` or `1.2.3` will be rejected by npm. Use a descriptive name instead.
+
+- **`latest`** — The default tag. This is what users get with a plain `npm install`. Should only be used for releases from `main`.
+- **Custom tags** (e.g. `v1-longlived`) — Used for releases from long-lived or experimental branches.
+
+Examples of **valid** dist-tags: `latest`, `next`, `beta`, `v1-longlived`
+Examples of **invalid** dist-tags: `5.0.0`, `1.2.3`, `6.0.0-rc.1` (these are semver and will be rejected)
+
+| ![Screenshot showcasing the npm distribution tags](assets/npm-dist-tags.png) |
+|---|
+| npm distribution tags |
+
+### Safety guard
+
+The workflow **blocks** publishing with the `latest` dist-tag from any branch other than `main`. This prevents accidentally overwriting `latest` with a version from an older or experimental branch. If you're releasing from a non-main branch, use the package's major version as the tag (e.g. `v5`).
+
+## Examples
+
+### Standard release from main
+
+Use default inputs — just pick the package:
+
+| Input | Value |
+|---|---|
+| `package` | `core` |
+| `branch` | `main` (default) |
+| `npm-tag` | `latest` (default) |
+| `test-all` | `false` (default) |
+
+This publishes the version in `packages/core/package.json` on `main` as `@actions/core@latest`.
+
+### Patch release from a long-lived branch
+
+| Input | Value |
+|---|---|
+| `package` | `artifact` |
+| `branch` | `releases/v5` |
+| `npm-tag` | `v5` |
+| `test-all` | `false` (default) |
+
+This publishes the version in `packages/artifact/package.json` on the `releases/v5` branch under the `v5` dist-tag. The `latest` tag remains untouched.
+
+### Release with full test suite
+
+| Input | Value |
+|---|---|
+| `package` | `cache` |
+| `branch` | `main` (default) |
+| `npm-tag` | `latest` (default) |
+| `test-all` | `true` |
+
+Same as a standard release, but runs tests for all packages before publishing.
+
+## Prerequisites
+
+- You must have permission to trigger workflows on this repository.
+- The `npm-publish` environment must be configured with npm credentials and OIDC.
+- The `SLACK` secret must be set for Slack notifications to work.

package-lock.json

@@ -13278,9 +13278,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "dev": true,
       "license": "MIT",
       "engines": {

packages/artifact/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@actions/artifact",
-  "version": "6.2.0",
+  "version": "6.2.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@actions/artifact",
-      "version": "6.2.0",
+      "version": "6.2.1",
       "license": "MIT",
       "dependencies": {
         "@actions/core": "^3.0.0",
@@ -1812,9 +1812,9 @@
       "license": "MIT"
     },
     "node_modules/undici": {
-      "version": "6.23.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-6.23.0.tgz",
-      "integrity": "sha512-VfQPToRA5FZs/qJxLIinmU59u0r7LXqoJkCzinq3ckNJp3vKEh7jTWN589YQ5+aoAC/TGRLyJLCPKcLQbM8r9g==",
+      "version": "6.24.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.0.tgz",
+      "integrity": "sha512-lVLNosgqo5EkGqh5XUDhGfsMSoO8K0BAN0TyJLvwNRSl4xWGZlCVYsAIpa/OpA3TvmnM01GWcoKmc3ZWo5wKKA==",
       "license": "MIT",
       "engines": {
         "node": ">=18.17"