|
| 1 | +# npm Release |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The npm Release workflow is designed to be triggered manually via `workflow_dispatch` with configurable input parameters. It performs a comprehensive npm package release process including tag validation, testing, Git tag creation, package publishing to npm registry, and GitHub release creation. |
| 6 | + |
| 7 | +## Trigger |
| 8 | + |
| 9 | +This workflow is triggered manually via `workflow_dispatch` with configurable input parameters. |
| 10 | + |
| 11 | +## Workflow Details |
| 12 | + |
| 13 | +### Jobs |
| 14 | + |
| 15 | +#### `check-tag` |
| 16 | +- **Runner**: `ubuntu-latest` |
| 17 | +- **Purpose**: Validates that the release tag does not already exist to prevent duplicate releases |
| 18 | +- **Condition**: Only runs if not in dry-run mode (`!inputs.dry-run`) |
| 19 | +- **Uses **: `netcracker/qubership-workflow-hub/actions/[email protected]` |
| 20 | + |
| 21 | +#### `npm-test` |
| 22 | +- **Runner**: `ubuntu-latest` (via reusable workflow) |
| 23 | +- **Purpose**: Performs a dry-run test of the npm package publishing process |
| 24 | +- **Dependencies**: Requires `check-tag` job completion |
| 25 | +- **Uses **: `Netcracker/qubership-workflow-hub/.github/workflows/[email protected]` |
| 26 | +- **Condition**: Always runs regardless of previous job status |
| 27 | + |
| 28 | +#### `npm-publish` |
| 29 | +- **Runner**: `ubuntu-latest` (via reusable workflow) |
| 30 | +- **Purpose**: Publishes the npm package to the registry |
| 31 | +- **Dependencies**: Requires `npm-test` job completion |
| 32 | +- **Condition**: Only runs if not in dry-run mode (`!inputs.dry-run`) |
| 33 | +- **Uses **: `Netcracker/qubership-workflow-hub/.github/workflows/[email protected]` |
| 34 | + |
| 35 | +#### `tag` |
| 36 | +- **Runner**: `ubuntu-latest` (via reusable workflow) |
| 37 | +- **Purpose**: Creates a Git tag for the release |
| 38 | +- **Dependencies**: Requires `npm-publish` job completion |
| 39 | +- **Condition**: Only runs if not in dry-run mode (`!inputs.dry-run`) |
| 40 | +- **Uses **: `netcracker/qubership-workflow-hub/.github/workflows/[email protected]` |
| 41 | + |
| 42 | +#### `github-release` |
| 43 | +- **Runner**: `ubuntu-latest` (via reusable workflow) |
| 44 | +- **Purpose**: Creates a GitHub release from the Git tag |
| 45 | +- **Dependencies**: Requires `tag` job completion |
| 46 | +- **Condition**: Only runs if not in dry-run mode (`!inputs.dry-run`) |
| 47 | +- **Uses **: `netcracker/qubership-workflow-hub/.github/workflows/[email protected]` |
| 48 | + |
| 49 | +### Workflow Sequence |
| 50 | + |
| 51 | +1. **Tag Validation** → **Package Test** → **Publishing** → **Tag Creation** → **Release Creation** |
| 52 | + |
| 53 | +In dry-run mode: |
| 54 | +- Only tag validation and package test are executed |
| 55 | +- No publishing, tagging, or release creation occurs |
| 56 | + |
| 57 | +## Delegated Tasks |
| 58 | + |
| 59 | +The workflow delegates the actual npm publishing process to the `re-npm-publish.yml` workflow from the `qubership-workflow-hub` repository, which performs: |
| 60 | + |
| 61 | +1. Repository checkout |
| 62 | +2. Node.js environment setup |
| 63 | +3. Dependency installation |
| 64 | +4. Lerna monorepo detection (if applicable) |
| 65 | +5. Dependency updates (if required) |
| 66 | +6. Package version updates in package.json or lerna.json |
| 67 | +7. Project build |
| 68 | +8. Test execution |
| 69 | +9. Changes commit and push |
| 70 | +10. Package publishing to npm registry |
| 71 | + |
| 72 | +## Configuration |
| 73 | + |
| 74 | +### Required Input Parameters |
| 75 | +- `version` (string, required): Release version for npm (e.g., 1.0.0) |
| 76 | + |
| 77 | +### Optional Input Parameters |
| 78 | +- `scope` (string, optional): npm scope for the package (default: `@netcracker`) |
| 79 | +- `node-version` (string, optional): Node.js version to use (default: `22.x`) |
| 80 | +- `registry-url` (string, optional): npm registry URL (default: `https://npm.pkg.github.com`) |
| 81 | +- `update-nc-dependency` (boolean, optional): Update @netcracker dependencies (default: `false`) |
| 82 | +- `dry-run` (boolean, optional): Run in dry-run mode without actual publishing (default: `false`) |
| 83 | +- `npm-dist-tag` (string, optional): npm distribution tag (default: `latest`) |
| 84 | + |
| 85 | +### Permissions |
| 86 | +- `contents: write` - For creating Git tags and GitHub releases |
| 87 | +- `packages: write` - For publishing npm packages to the registry |
| 88 | + |
| 89 | +### Environment Variables |
| 90 | +- `GITHUB_TOKEN` - Used for GitHub API operations and npm authentication |
| 91 | + |
| 92 | +## Prerequisites |
| 93 | + |
| 94 | +Before using this workflow, you need to: |
| 95 | + |
| 96 | +1. **Adjust package.json** |
| 97 | + - Ensure proper project configuration |
| 98 | + - Set up scopes and registry information if using scoped packages |
| 99 | + |
| 100 | +2. **Create GitHub release configuration** |
| 101 | + - Add or configure release drafter configuration file |
| 102 | + - This is used by the release creation step |
| 103 | + |
| 104 | +3. **Review qubership-workflow-hub documentation** |
| 105 | + - See: [npm publish reusable workflow](https://github.com/Netcracker/qubership-workflow-hub/blob/main/docs/reusable/npm-publish.md) |
| 106 | + - Contains detailed npm project publish/release workflow instructions |
| 107 | + |
| 108 | +## Usage |
| 109 | + |
| 110 | +### Production Release |
| 111 | + |
| 112 | +1. Trigger the workflow manually from GitHub Actions |
| 113 | +2. Provide the release version (e.g., 1.0.0) |
| 114 | +3. Configure optional parameters as needed |
| 115 | +4. Leave `dry-run` as `false` (default) |
| 116 | +5. Workflow will: |
| 117 | + - Validate the tag doesn't exist |
| 118 | + - Run tests in dry-run mode |
| 119 | + - Publish the package to npm |
| 120 | + - Create a Git tag |
| 121 | + - Create a GitHub release |
| 122 | + |
| 123 | +### Dry-Run Testing |
| 124 | + |
| 125 | +1. Trigger the workflow manually from GitHub Actions |
| 126 | +2. Set `dry-run` to `true` |
| 127 | +3. Provide any desired parameters |
| 128 | +4. Workflow will: |
| 129 | + - Validate the tag (if specified) |
| 130 | + - Run tests without publishing |
| 131 | + - Report results without creating tags or releases |
| 132 | + - Useful for validating the release process |
| 133 | + |
| 134 | +### Monorepo Projects |
| 135 | + |
| 136 | +For Lerna monorepos: |
| 137 | + |
| 138 | +1. Ensure the project is properly configured as a Lerna monorepo |
| 139 | +2. Set `update-nc-dependency` to `true` if needed to update @netcracker dependencies |
| 140 | +3. The workflow will automatically detect and handle Lerna configuration |
| 141 | + |
| 142 | +## Features |
| 143 | + |
| 144 | +- **Tag validation**: Prevents duplicate releases by checking for existing tags |
| 145 | +- **Dry-run support**: Test the entire release process without publishing |
| 146 | +- **Comprehensive testing**: Runs tests before publishing to ensure quality |
| 147 | +- **Monorepo support**: Automatically detects and handles Lerna monorepos |
| 148 | +- **Scoped packages**: Supports @netcracker scoped packages |
| 149 | +- **Distribution tags**: Allows setting custom npm distribution tags |
| 150 | +- **GitHub integration**: Creates releases automatically after publishing |
| 151 | +- **Manual control**: Manually triggered for precise release management |
| 152 | +- **Dependency management**: Can update @netcracker dependencies during release |
| 153 | + |
| 154 | +## Important Notes |
| 155 | + |
| 156 | +- This workflow is designed for **production releases** and should be triggered manually when ready to publish |
| 157 | +- Version parameter is required for production releases |
| 158 | +- In dry-run mode, no actual publishing, tagging, or release creation occurs |
| 159 | +- Duplicate release prevention is handled by tag validation |
| 160 | +- All operations are logged in the GitHub Actions workflow summary |
| 161 | + |
| 162 | +## Categories |
| 163 | +- Node.js |
| 164 | +- npm |
| 165 | +- Automation |
| 166 | +- Release Management |
| 167 | + |
| 168 | +## Labels |
| 169 | +- npm |
| 170 | +- release |
| 171 | +- node |
| 172 | +- publishing |
| 173 | +- automation |
0 commit comments