feat(release): add support for build artifacts, tarballs, and access control

Co-authored-by: neilime <[email protected]>

Author: Copilot

.github/workflows/release.md

@@ -25,10 +25,13 @@
 
 Workflow to release Node.js packages with support for:
 
-- Generating documentation (optional)
 - Publishing to various registries (npm, GitHub Packages)
+- Publishing from build artifacts or source code
+- Publishing pre-built package tarballs
+- Generating documentation (optional)
 - Provenance attestation for npm packages
 - Distribution tags for versioning
+- Scoped package access control
 
 ### Permissions
 
@@ -42,6 +45,8 @@ Workflow to release Node.js packages with support for:
 
 ## Usage
 
+### Basic Release from Source
+
 ```yaml
 name: Release
 
@@ -59,43 +64,77 @@ jobs:
       packages: write
       id-token: write
     secrets:
-      # Authentication token for the registry.
-      # For npm: Use an npm access token with publish permissions.
-      # For GitHub Packages: Use `GITHUB_TOKEN` or a PAT with `packages:write` permission.
+      registry-token: ${{ secrets.NPM_TOKEN }}
+```
+
+### Release with Build Artifacts from CI
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ["*"]
+
+permissions: {}
+
+jobs:
+  ci:
+    uses: ./.github/workflows/__shared-ci.yml
+    permissions:
+      contents: read
+      id-token: write
+      packages: read
+    secrets: inherit
+
+  release:
+    needs: ci
+    uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    secrets:
       registry-token: ${{ secrets.NPM_TOKEN }}
     with:
-      # JSON array of runner(s) to use.
-      # Default: `["ubuntu-latest"]`
-      runs-on: '["ubuntu-latest"]'
+      # Download build artifacts from CI job
+      build-artifact-id: ${{ needs.ci.outputs.build-artifact-id }}
+      access: public
+```
 
-      # Documentation generation parameters.
-      # Set to empty string or `false` to disable.
-      docs: ""
+### Release Pre-built Tarball
 
-      # Registry configuration.
-      # Use `npm`, `github`, or a URL/JSON object.
-      # Default: `npm`
-      registry: npm
+```yaml
+name: Release
 
-      # Command to run for publishing.
-      # Default: `publish`
-      publish-command: publish
+on:
+  push:
+    tags: ["*"]
 
-      # npm distribution tag.
-      # Default: `latest`
-      tag: latest
+permissions: {}
 
-      # Whether to perform a dry run.
-      # Default: `false`
-      dry-run: false
+jobs:
+  ci:
+    uses: ./.github/workflows/__shared-ci.yml
+    permissions:
+      contents: read
+      id-token: write
+    secrets: inherit
 
-      # Whether to generate provenance attestation.
-      # Default: `true`
+  release:
+    needs: ci
+    uses: hoverkraft-tech/ci-github-nodejs/.github/workflows/release.yml@main
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    secrets:
+      registry-token: ${{ secrets.NPM_TOKEN }}
+    with:
+      build-artifact-id: ${{ needs.ci.outputs.package-tarball-artifact-id }}
+      package-tarball: "*.tgz"
+      access: public
       provenance: true
-
-      # Working directory where the package is located.
-      # Default: `.`
-      working-directory: .
 ```
 
 <!-- usage:end -->
@@ -112,6 +151,12 @@ jobs:
 | ----------------------- | ---------------------------------------------------------------------------------- | ------------ | ----------- | ------------------- |
 | **`runs-on`**           | JSON array of runner(s) to use.                                                    | **false**    | **string**  | `["ubuntu-latest"]` |
 |                         | See <https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job>. |              |             |                     |
+| **`build-artifact-id`** | Build artifact ID from CI to download before publishing.                           | **false**    | **string**  | -                   |
+|                         | Contains built package or tarball from a previous job.                             |              |             |                     |
+| **`package-tarball`**   | Path/pattern to pre-built tarball to publish (e.g., `*.tgz`).                      | **false**    | **string**  | -                   |
+|                         | Use when publishing a specific tarball instead of from source.                     |              |             |                     |
+| **`access`**            | Package access level: `public` or `restricted`.                                    | **false**    | **string**  | -                   |
+|                         | Leave empty to use package.json default.                                           |              |             |                     |
 | **`docs`**              | Documentation generation parameters.                                               | **false**    | **string**  | -                   |
 |                         | Set to empty string or `false` to disable.                                         |              |             |                     |
 |                         | Set to `true` for default command (`docs`).                                        |              |             |                     |

.github/workflows/release.yml

@@ -15,6 +15,31 @@ on:
         type: string
         default: '["ubuntu-latest"]'
         required: false
+      build-artifact-id:
+        description: |
+          Build artifact ID from a previous CI job to download before publishing.
+          This artifact typically contains the built package or tarball.
+          If not provided, the workflow will publish from source.
+        type: string
+        required: false
+        default: ""
+      package-tarball:
+        description: |
+          Path to a pre-built package tarball to publish (e.g., `my-package-1.0.0.tgz`).
+          Use this when publishing a specific tarball file instead of running npm publish from source.
+          Supports glob patterns to match tarball files.
+        type: string
+        required: false
+        default: ""
+      access:
+        description: |
+          Package access level for npm publish.
+          - `public` — Publicly accessible package
+          - `restricted` — Scoped package with restricted access
+          Leave empty to use package.json default.
+        type: string
+        required: false
+        default: ""
       docs:
         description: |
           Documentation generation parameters.
@@ -253,6 +278,13 @@ jobs:
           working-directory: ${{ inputs.working-directory }}
           registry-url: ${{ needs.prepare.outputs.registry-url }}
 
+      - name: Download build artifacts
+        if: inputs.build-artifact-id != ''
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        with:
+          artifact-ids: ${{ inputs.build-artifact-id }}
+          path: /
+
       - id: package-info
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         env:
@@ -345,6 +377,8 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.registry-token }}
           PUBLISH_COMMAND: ${{ inputs.publish-command }}
+          PACKAGE_TARBALL: ${{ inputs.package-tarball }}
+          ACCESS: ${{ inputs.access }}
           TAG: ${{ inputs.tag }}
           DRY_RUN: ${{ inputs.dry-run }}
           PROVENANCE: ${{ inputs.provenance }}
@@ -355,6 +389,7 @@ jobs:
           script: |
             const fs = require('node:fs');
             const path = require('node:path');
+            const { glob } = require('glob');
 
             let workingDirectory = process.env.WORKING_DIRECTORY || '.';
             if (!path.isAbsolute(workingDirectory)) {
@@ -366,15 +401,50 @@ jobs:
             }
 
             const publishCommand = process.env.PUBLISH_COMMAND;
+            const packageTarball = process.env.PACKAGE_TARBALL;
+            const access = process.env.ACCESS;
             const tag = process.env.TAG;
             const dryRun = process.env.DRY_RUN === 'true';
             const provenance = process.env.PROVENANCE === 'true';
             const runScriptCommand = process.env.RUN_SCRIPT_COMMAND;
             const registryUrl = process.env.REGISTRY_URL;
 
+            // Determine what to publish
+            let publishTarget = null;
+
+            if (packageTarball) {
+              // Publishing a specific tarball file
+              const tarballPattern = path.isAbsolute(packageTarball) 
+                ? packageTarball 
+                : path.join(workingDirectory, packageTarball);
+              
+              const matches = await glob(tarballPattern, { nodir: true });
+              
+              if (matches.length === 0) {
+                return core.setFailed(`No tarball found matching pattern: ${packageTarball}`);
+              }
+              
+              if (matches.length > 1) {
+                core.warning(`Multiple tarballs found: ${matches.join(', ')}. Using first match.`);
+              }
+              
+              publishTarget = matches[0];
+              core.info(`Publishing tarball: ${publishTarget}`);
+            }
+
             // Build publish arguments
             const args = [publishCommand];
 
+            // Add tarball target if specified
+            if (publishTarget) {
+              args.push(publishTarget);
+            }
+
+            // Add access flag
+            if (access) {
+              args.push('--access', access);
+            }
+
             // Add tag
             if (tag) {
               args.push('--tag', tag);