{"id":42199430,"url":"https://github.com/joshjohanning/npm-version-check-action","last_synced_at":"2026-04-03T17:00:52.960Z","repository":{"id":315495025,"uuid":"1059741423","full_name":"joshjohanning/npm-version-check-action","owner":"joshjohanning","description":"GitHub Action that validates npm package version increments in pull requests to ensure proper semantic versioning","archived":false,"fork":false,"pushed_at":"2026-03-31T03:20:25.000Z","size":4973,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-01T16:39:49.127Z","etag":null,"topics":["actions","github","javascript","node-action"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshjohanning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-18T21:59:06.000Z","updated_at":"2026-03-30T20:19:18.000Z","dependencies_parsed_at":"2025-09-19T00:36:26.651Z","dependency_job_id":"37cf8683-e1eb-4075-943d-72e6708817cc","html_url":"https://github.com/joshjohanning/npm-version-check-action","commit_stats":null,"previous_names":["joshjohanning/npm-version-check-action"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/joshjohanning/npm-version-check-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fnpm-version-check-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fnpm-version-check-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fnpm-version-check-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fnpm-version-check-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshjohanning","download_url":"https://codeload.github.com/joshjohanning/npm-version-check-action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fnpm-version-check-action/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31364574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","github","javascript","node-action"],"created_at":"2026-01-27T00:22:43.121Z","updated_at":"2026-04-03T17:00:52.853Z","avatar_url":"https://github.com/joshjohanning.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# npm-version-check-action\n\n[![GitHub release](https://img.shields.io/github/release/joshjohanning/npm-version-check-action.svg?labelColor=333)](https://github.com/joshjohanning/npm-version-check-action/releases)\n[![GitHub marketplace](https://img.shields.io/badge/marketplace-npm--version--check--action-blue?logo=github)](https://github.com/marketplace/actions/npm-version-check-action)\n[![CI](https://github.com/joshjohanning/npm-version-check-action/actions/workflows/ci.yml/badge.svg)](https://github.com/joshjohanning/npm-version-check-action/actions/workflows/ci.yml)\n[![Publish GitHub Action](https://github.com/joshjohanning/npm-version-check-action/actions/workflows/publish.yml/badge.svg)](https://github.com/joshjohanning/npm-version-check-action/actions/workflows/publish.yml)\n![Coverage](./badges/coverage.svg)\n\n🔍 **GitHub Action that validates npm package version increments in pull requests to ensure proper semantic versioning**\n\nThis action prevents developers from forgetting to bump package.json version before merging PRs that contain code changes, which would cause publishing issues later.\n\n## What's new\n\nPlease refer to the [release page](https://github.com/joshjohanning/npm-version-check-action/releases) for the latest release notes.\n\n## ✨ Features\n\n- 🎯 **Smart file detection** - Only runs when JavaScript/TypeScript/package files are modified\n- 🧠 **Intelligent dependency checking** - Distinguishes between actual dependency changes vs metadata-only changes in package.json and package-lock.json\n- 🔒 **Version consistency check** - Validates that package.json and package-lock.json have matching versions\n- 🔧 **Configurable devDependencies handling** - Choose whether devDependency changes should trigger version bumps\n- ⏭️ **Per-commit skip support** - Use `[skip version]` in commit messages to exclude specific commits from version checking\n- 📊 **Semantic versioning validation** - Ensures new version is higher than previous release\n- 🏷️ **Git tag comparison** - Compares against the latest git tag\n- 🚀 **Shallow clone compatible** - Automatically fetches tags, works with default checkout\n- 🎉 **First release support** - Gracefully handles repositories with no previous tags\n- 🚀 **JavaScript action** - Fast execution with Node.js runtime\n- 🔄 **Node.js Actions runtime change detection** - Requires a major version bump when `action.yml` changes its Node.js Actions runtime (e.g., `node20` to `node24`)\n- 📝 **Clear messaging** - Provides detailed success/error messages with emojis\n- ⚙️ **Configurable** - Supports custom package.json paths, tag prefixes, and dependency policies\n\n## 📋 Requirements\n\n- Node.js project with `package.json`\n- Git tags following semantic versioning (e.g., `v1.0.0`, `v2.1.3`)\n- Used in pull request workflows\n- **Permissions**: `contents: read` and `pull-requests: read` (the action uses the Pulls API to analyze commits)\n\n## 🚀 Usage\n\n### Basic Usage\n\nAdd this step to your workflow file (e.g., `.github/workflows/ci.yml`):\n\n```yaml\nname: CI\non:\n  pull_request:\n    branches: [main]\n\njobs:\n  version-check:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pull-requests: read\n    steps:\n      - uses: actions/checkout@v6\n\n      - uses: joshjohanning/npm-version-check-action@v2\n```\n\n\u003e **Note:** The `pull-requests: read` permission is required because the action\n\u003e uses the GitHub Pulls API to retrieve commits from the pull request for\n\u003e per-commit file analysis and `[skip version]` keyword support.\n\n### Advanced Configuration\n\n```yaml\njobs:\n  version-check:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pull-requests: read\n    steps:\n      - uses: actions/checkout@v6\n\n      - uses: joshjohanning/npm-version-check-action@v2\n        with:\n          package-path: 'packages/core/package.json' # Custom package.json path\n          tag-prefix: 'v' # Tag prefix (default: 'v')\n          skip-files-check: 'false' # Always run, don't check files\n          include-dev-dependencies: 'true' # Require version bump for devDependencies\n```\n\n### Complete Workflow Example\n\n```yaml\nname: CI\non:\n  pull_request:\n    branches: [main, develop]\n  push:\n    branches: [main]\n\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pull-requests: read\n\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v6\n\n      - name: Check version increment\n        uses: joshjohanning/npm-version-check-action@v2\n        with:\n          package-path: 'package.json'\n          tag-prefix: 'v'\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v6\n        with:\n          node-version: '24'\n          cache: 'npm'\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Run tests\n        run: npm test\n```\n\n## 📥 Inputs\n\n| Input                                  | Description                                                                                             | Required | Default               |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- | --------------------- |\n| `package-path`                         | Path to package.json file (relative to repository root)                                                 | No       | `package.json`        |\n| `tag-prefix`                           | Prefix for version tags (e.g., \"v\" for v1.0.0)                                                          | No       | `v`                   |\n| `skip-files-check`                     | Skip checking if JS/package files changed (always run version check)                                    | No       | `false`               |\n| `include-dev-dependencies`             | Whether devDependency changes should trigger version bump requirement                                   | No       | `false`               |\n| `skip-version-keyword`                 | Keyword in commit messages to skip version check for that commit's files. Set to `''` to disable        | No       | `[skip version]`      |\n| `skip-version-consistency-check`       | Skip the check that validates package.json and package-lock.json have matching versions                 | No       | `false`               |\n| `skip-major-on-actions-runtime-change` | Skip the check that requires a major version bump when `action.yml` changes its Node.js Actions runtime | No       | `false`               |\n| `token`                                | GitHub token for API access (required for `skip-version-keyword` to analyze commits)                    | No       | `${{ github.token }}` |\n\n## 📤 Outputs\n\n| Output             | Description                                                                        |\n| ------------------ | ---------------------------------------------------------------------------------- |\n| `version-changed`  | Whether the version was changed (`true`/`false`)                                   |\n| `current-version`  | Current version from package.json                                                  |\n| `previous-version` | Previous version from latest git tag                                               |\n| `runtime-changed`  | Whether the Node.js Actions runtime version in action.yml changed (`true`/`false`) |\n\n### Using Outputs\n\n```yaml\n- name: Check version\n  id: version-check\n  uses: joshjohanning/npm-version-check-action@v2\n\n- name: Print version info\n  run: |\n    echo \"Version changed: ${{ steps.version-check.outputs.version-changed }}\"\n    echo \"Current version: ${{ steps.version-check.outputs.current-version }}\"\n    echo \"Previous version: ${{ steps.version-check.outputs.previous-version }}\"\n```\n\n## 🎯 How It Works\n\n1. **Smart File Change Detection**: Analyzes which files were modified in the PR\n   - JavaScript/TypeScript files trigger version checks\n   - Package files (`package.json`, `package-lock.json`) undergo intelligent dependency analysis\n2. **Intelligent Dependency Analysis**: For package files, distinguishes between:\n   - **Functional changes**: Actual dependency additions, updates, or removals that affect functionality\n   - **Metadata changes**: Version bumps, description updates, scripts changes, or devDependency changes that don't affect runtime\n3. **Version Consistency Check**: Validates that `package.json` and `package-lock.json` have matching versions\n   - Prevents issues where one file is updated but the other is not (e.g., after rebasing or manual edits)\n   - Fails the build with a clear error message if versions don't match\n4. **Version Extraction**: Reads the current version from `package.json`\n5. **Tag Comparison**: Fetches the latest git tag and compares versions\n6. **Semantic Validation**: Ensures the new version is higher than the previous release\n7. **Runtime Change Detection**: Checks if `action.yml` changed its Node.js Actions runtime and requires a major version bump\n8. **Clear Feedback**: Provides success or error messages with actionable hints\n\n### Smart File Detection\n\nThe action intelligently handles different types of file changes:\n\n#### JavaScript/TypeScript Files (Always Trigger Version Check)\n\n- `.js` - JavaScript files\n- `.ts` - TypeScript files\n- `.jsx` - React JavaScript files\n- `.tsx` - React TypeScript files\n\n#### Package Files (Smart Dependency Analysis)\n\n- `package.json` - Only triggers version check for **dependency changes**, not metadata\n  - ✅ **Triggers check**: Changes to `dependencies`, `peerDependencies`, `optionalDependencies`, `bundleDependencies`\n  - ✅ **Triggers check (configurable)**: Changes to `devDependencies` when `include-dev-dependencies: true`\n  - ❌ **Skips check**: Changes to `version`, `description`, `scripts`, `author`, etc.\n- `package-lock.json` - **Smart handling with dependency tree analysis**\n  - ✅ **Always triggers check**: Production dependency changes (new packages, version updates, integrity changes)\n  - 🔄 **Configurable behavior**: When only devDependencies changed in package.json:\n    - ❌ **Skips check** if `include-dev-dependencies: false` (default) - lockfile changes caused by devDependency updates (including shared transitive dependency reshuffling) are correctly identified and ignored\n    - ✅ **Triggers check** if `include-dev-dependencies: true` - package-lock.json changes are analyzed\n  - ❌ **Skips check**: Pure metadata changes (version bumps, format updates)\n\n#### 🎯 Key Improvement: Dependency Tree Walking for Lockfile Analysis\n\nWhen `include-dev-dependencies: false` (default) and only devDependencies change in package.json:\n\n- The action walks the dependency tree from each changed devDependency to identify which lockfile changes are attributable to the devDep update\n- Shared transitive dependencies (packages used by both production and dev trees) that get reshuffled by npm are correctly treated as dev-only changes, even when npm nests them under production dependency paths (e.g., `node_modules/cliui/node_modules/ansi-regex`), but only when corroborated by a confirmed dev-attributable change of the same package name at another path\n- Lockfile changes to packages whose **name** does not appear in any confirmed dev-attributable changed entry are still flagged as production changes (e.g., intentional transitive bumps for security fixes)\n\nThis intelligent approach prevents unnecessary version bumps when only non-functional changes are made.\n\n## 📋 Version Increment Examples\n\n| Previous | Current | Result           |\n| -------- | ------- | ---------------- |\n| `1.0.0`  | `1.0.1` | ✅ Valid (patch) |\n| `1.0.0`  | `1.1.0` | ✅ Valid (minor) |\n| `1.0.0`  | `2.0.0` | ✅ Valid (major) |\n| `1.0.0`  | `1.0.0` | ❌ Same version  |\n| `1.1.0`  | `1.0.5` | ❌ Lower version |\n\n## 🛠️ Common Use Cases\n\n### Monorepo Support\n\nFor monorepos with multiple packages:\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    package-path: 'packages/frontend/package.json'\n\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    package-path: 'packages/backend/package.json'\n```\n\n### Custom Tag Format\n\nIf your tags don't use the `v` prefix:\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    tag-prefix: 'release-' # For tags like 'release-1.0.0'\n```\n\n### Always Run (Skip File Check)\n\nTo always validate version regardless of changed files:\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    skip-files-check: 'true'\n```\n\n### DevDependencies Configuration\n\nBy default, `devDependencies` changes don't trigger version bump requirements since they typically don't affect production functionality. The action uses **smart logic** to handle this configuration:\n\n#### Default Behavior (Ignore DevDependencies) - Recommended\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    include-dev-dependencies: 'false' # Default - devDeps don't require version bump\n```\n\n**What happens with this setting:**\n\n- 🎯 **package.json**: Only production dependencies (`dependencies`, `peerDependencies`, etc.) trigger version checks\n- 🚫 **package-lock.json**: When only devDependencies changed in package.json, lock file changes are **completely ignored**\n- ✅ **Result**: No false positives from massive lock file changes due to dev dependency updates\n\n#### Strict Mode (Include DevDependencies)\n\nFor libraries where build tools/devDependencies can affect the published package:\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    include-dev-dependencies: 'true' # devDeps changes require version bump\n```\n\n**What happens with this setting:**\n\n- ✅ **package.json**: Both production AND development dependencies trigger version checks\n- ✅ **package-lock.json**: All dependency changes are analyzed, including dev dependency effects\n\n#### Use Cases for Including DevDependencies\n\n- **Library packages**: Where build tools, bundlers, or transpilers can affect the final output\n- **Strict versioning policies**: Teams that want every dependency change tracked\n- **CI/CD sensitive packages**: Where test runners or build scripts changes impact deliverables\n\n### Skip Version Check for Specific Commits\n\nSometimes you need to make changes that shouldn't require a version bump - like fixing a typo in a comment, updating JSDoc, or fixing linting issues. You can use the `[skip version]` keyword in your commit message to exclude that commit's files from version checking:\n\n```bash\n# This commit's files will be excluded from version check\ngit commit -m \"docs: fix typo in JSDoc comment [skip version]\"\n\n# This commit's files will still be checked\ngit commit -m \"feat: add new feature\"\n```\n\n#### How It Works\n\nThe action analyzes each commit in the PR individually:\n\n1. Commits **with** `[skip version]` in the message → files are **excluded** from version check\n2. Commits **without** the keyword → files are **included** in version check\n3. If a file is changed in **both** skipped and non-skipped commits → file is **included** (requires version bump)\n\n#### Example Scenario\n\n```\nPR with 3 commits:\n├── Commit A: \"docs: fix typos [skip version]\" → changes src/index.js\n├── Commit B: \"feat: add feature\" → changes src/utils.js\n└── Commit C: \"fix: typo\" → changes src/index.js (same file as A)\n\nResult: src/index.js and src/utils.js both require version check\n        (index.js because it's changed in non-skipped Commit C)\n```\n\n#### Custom Skip Keyword\n\nYou can customize the skip keyword or disable this feature entirely:\n\n```yaml\n# Use a custom keyword\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    skip-version-keyword: '[no bump]'\n\n# Disable skip functionality entirely\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    skip-version-keyword: ''\n```\n\n## 🔍 Troubleshooting\n\n### \"No previous version tag found\"\n\nThis is normal for the first release. The action will pass and allow the PR to proceed.\n\n### \"Could not extract version from package.json\"\n\nEnsure your `package.json` has a valid `version` field:\n\n```json\n{\n  \"name\": \"my-package\",\n  \"version\": \"1.0.0\"\n}\n```\n\n### \"Warning: Could not fetch git tags\"\n\nThe action automatically fetches git tags to work with shallow clones. If this warning appears, it means there was an issue fetching tags, but the action will continue with limited functionality. This is rare and usually indicates network or permission issues.\n\n### Node.js Actions Runtime Change Detection\n\nWhen `skip-major-on-actions-runtime-change` is `false` (default), the action compares the `runs.using` field in `action.yml` between the base and head of the PR. If the Node.js Actions runtime version changes (e.g., `node20` to `node24`), a **major** version bump is required.\n\nThis follows the convention used by popular GitHub Actions (like `actions/checkout`, `actions/setup-node`, etc.) where runtime upgrades are treated as breaking changes since they may affect consumers who pin to specific major versions.\n\n```yaml\n# action.yml before:\nruns:\n  using: 'node20'\n\n# action.yml after:\nruns:\n  using: 'node24'\n\n# Requires: v1.x.x -\u003e v2.0.0 (major version bump)\n# Would fail: v1.x.x -\u003e v1.x.x (minor/patch bump)\n```\n\nTo disable this check:\n\n```yaml\n- uses: joshjohanning/npm-version-check-action@v2\n  with:\n    skip-major-on-actions-runtime-change: 'true'\n```\n\n### \"Version check passed but I expected it to fail\"\n\nIf you made changes to `devDependencies` and expected a version bump requirement:\n\n1. **Check the default behavior**: By default, `devDependencies` changes don't require version bumps\n2. **Configure if needed**: Set `include-dev-dependencies: 'true'` to require version bumps for devDependency changes\n3. **Review smart detection**: The action distinguishes between functional dependency changes and metadata-only changes\n\n### \"I updated devDependencies and package-lock.json changed massively, but no version bump required?\"\n\nThis is the **expected behavior** with the default configuration! 🎉\n\n- ✅ **Working as designed**: When `include-dev-dependencies: false` (default), massive package-lock.json changes from dev dependency updates are intentionally ignored\n- 🚫 **No false positives**: The action completely skips package-lock.json analysis when only devDependencies changed\n- 🎯 **Smart logic**: This prevents the _\"I'm only updating devDependencies :(\"_ problem\n- ⚙️ **Configurable**: Set `include-dev-dependencies: true` if you want dev dependency changes to require version bumps\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## 📞 Support\n\nIf you have any questions or run into issues, please [open an issue](https://github.com/joshjohanning/npm-version-check-action/issues) on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshjohanning%2Fnpm-version-check-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshjohanning%2Fnpm-version-check-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshjohanning%2Fnpm-version-check-action/lists"}