feat: add npm publishing pipeline with GitHub Actions #42
Conversation
WalkthroughAdds GitHub Actions workflows and semantic-release configuration to automate releases (production, staging, PR dry-run), moves package entry points to a Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touchesImportant Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error)
✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
aspiers
force-pushed
the
publish-pipeline
branch
from
8d87809 to
73b5bfc
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
.github/workflows/create-prerelease-lexicon.yml (1)
17-19: Consider adding additional permissions for semantic-release.The workflow only has
contents: writepermission, but semantic-release with the GitHub plugin may need additional permissions to:
- Create GitHub releases
- Comment on issues and PRs
Compare with the
create-release-lexicon.ymlworkflow which includes:permissions: contents: write issues: write pull-requests: write id-token: writeApply this diff to add the missing permissions:
permissions: contents: write + issues: write + pull-requests: write + id-token: write.github/workflows/dryrun-release-ci-lexicon.yml (1)
10-11: Consider adding additional permissions for dry-run validation.Like the prerelease workflow, this workflow may benefit from additional permissions for semantic-release to fully validate the release process, even in dry-run mode:
permissions: contents: write issues: write pull-requests: write id-token: write
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
.github/workflows/create-prerelease-lexicon.yml(1 hunks).github/workflows/create-release-lexicon.yml(1 hunks).github/workflows/dryrun-release-ci-lexicon.yml(1 hunks).npmignore(0 hunks).releaserc.prerelease.yaml(1 hunks).releaserc.yaml(1 hunks)PUBLISHING.md(1 hunks)README.md(1 hunks)package.json(1 hunks)
💤 Files with no reviewable changes (1)
- .npmignore
🧰 Additional context used
📓 Path-based instructions (2)
!(types)/**/*.{js,ts,tsx,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
Run
npm run formatwith Prettier before committing to ensure consistent code formatting
Files:
.releaserc.prerelease.yamlpackage.json.github/workflows/create-prerelease-lexicon.yml.github/workflows/create-release-lexicon.ymlREADME.md.releaserc.yamlPUBLISHING.md.github/workflows/dryrun-release-ci-lexicon.yml
README.md
📄 CodeRabbit inference engine (Custom checks)
README.md: Ensure that all lexicons documented in README.md exist as JSON files in the lexicons/ directory
Ensure all properties documented in README.md match the actual JSON schema definitions in lexicons/**/*.json
Files:
README.md
🧠 Learnings (17)
📓 Common learnings
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 34
File: lexicons/org/hypercerts/claim/evaluation.json:45-63
Timestamp: 2025-12-15T10:13:17.689Z
Learning: For the hypercerts-lexicon repository, CI automatically runs `npm run gen-api` and `npm run check` to regenerate TypeScript types and validate lexicon definitions, so manual reminders about running these commands are not needed in code reviews.
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to !(types)/**/*.{js,ts,tsx,json,md} : Run `npm run format` with Prettier before committing to ensure consistent code formatting
Applied to files:
.releaserc.prerelease.yaml.releaserc.yaml
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to types/**/*.{ts,tsx} : Do not edit files in the `types/` directory manually - this directory contains auto-generated code that is regenerated by `npm run gen-api`
Applied to files:
package.json
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : After modifying lexicon JSON files, regenerate TypeScript types by running `npm run gen-api`
Applied to files:
package.jsonREADME.md
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: This repository contains ATProto lexicon definitions for the Hypercerts protocol with auto-generated TypeScript types - prioritize lexicon accuracy and consistency
Applied to files:
package.jsonREADME.md
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : Lexicon JSON files should follow the ATProto lexicon schema v1 specification
Applied to files:
package.jsonREADME.md
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : Organize lexicon files by namespace following the directory structure pattern (e.g., `org/hypercerts/claim/*.json`)
Applied to files:
package.jsonREADME.md
📚 Learning: 2025-12-15T10:13:17.689Z
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 34
File: lexicons/org/hypercerts/claim/evaluation.json:45-63
Timestamp: 2025-12-15T10:13:17.689Z
Learning: For the hypercerts-lexicon repository, CI automatically runs `npm run gen-api` and `npm run check` to regenerate TypeScript types and validate lexicon definitions, so manual reminders about running these commands are not needed in code reviews.
Applied to files:
package.json.github/workflows/create-prerelease-lexicon.yml.github/workflows/create-release-lexicon.ymlREADME.mdPUBLISHING.md
📚 Learning: 2025-12-15T15:33:19.949Z
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 37
File: lexicons/org/hypercerts/funding/receipt.json:1-71
Timestamp: 2025-12-15T15:33:19.949Z
Learning: In the hypercerts-lexicon repository, do not comment on Prettier/formatting issues in code reviews since they are reported by the lint workflow. Do not duplicate the lint output in reviews to reduce noise; focus review comments on functional/semantic issues and other non-formatting concerns.
Applied to files:
package.json
📚 Learning: 2025-12-11T15:44:24.397Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-11T15:44:24.397Z
Learning: Applies to lexicons/**/*.json : When adding, modifying, or deleting files in lexicons/**/*.json, update README.md to reflect changes (document new lexicons, update modified properties, remove deleted lexicons from documentation)
Applied to files:
.github/workflows/create-release-lexicon.ymlPUBLISHING.md
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : Update `README.md` documentation when adding or modifying lexicon definitions
Applied to files:
.github/workflows/create-release-lexicon.ymlREADME.mdPUBLISHING.md
📚 Learning: 2025-12-15T17:53:11.862Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : Run `npm run check` before committing to validate lexicon syntax and ensure valid lexicon definitions
Applied to files:
.github/workflows/create-release-lexicon.ymlREADME.mdPUBLISHING.md
📚 Learning: 2025-12-15T16:39:23.964Z
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 39
File: README.md:17-17
Timestamp: 2025-12-15T16:39:23.964Z
Learning: In the hypercerts-lexicon repository, standardize on the hyphenless spelling 'onchain' across Markdown documentation (e.g., README.md and other md files) to match the industry standard. Update any occurrences of 'on-chain' to 'onchain' and ensure consistency throughout all documentation.
Applied to files:
README.mdPUBLISHING.md
📚 Learning: 2025-12-11T15:44:24.397Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-11T15:44:24.397Z
Learning: Applies to lexicons/**/*.json : Verify that lexicon IDs in JSON files match what's documented in README.md
Applied to files:
README.md
📚 Learning: 2025-12-11T15:44:24.397Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-11T15:44:24.397Z
Learning: Applies to README.md : Ensure that all lexicons documented in README.md exist as JSON files in the lexicons/ directory
Applied to files:
README.md
📚 Learning: 2025-12-11T15:44:24.397Z
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-11T15:44:24.397Z
Learning: Applies to README.md : Ensure all properties documented in README.md match the actual JSON schema definitions in lexicons/**/*.json
Applied to files:
PUBLISHING.md
📚 Learning: 2025-12-15T15:33:19.949Z
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 37
File: lexicons/org/hypercerts/funding/receipt.json:1-71
Timestamp: 2025-12-15T15:33:19.949Z
Learning: For the hypercerts-org/hypercerts-lexicon repository, do not comment on Prettier formatting issues in code reviews because they are already reported by the lint workflow, and duplicating the report adds noise to the review.
Applied to files:
PUBLISHING.md
🔇 Additional comments (11)
README.md (1)
40-42: LGTM!Specifying the language for the code fence improves syntax highlighting and readability.
.releaserc.yaml (1)
1-10: LGTM! Standard semantic-release configuration.The configuration correctly defines the plugin stack for production releases on the
mainbranch and version branches. Ensure that the semantic-release plugins referenced here are installed (see comment on.releaserc.prerelease.yaml)..github/workflows/create-prerelease-lexicon.yml (2)
45-47: LGTM! Clever config swapping for prerelease branches.The conditional step to replace the release config with the prerelease config for non-main branches is a clean approach to handling different release strategies.
60-62: EnsureGH_PA_TOKENandNPM_TOKENsecrets are configured in GitHub.The workflow references these secrets for authentication. To configure them, navigate to the repository Settings, select Secrets and variables > Actions, click New repository secret, enter the name and value, then click Add secret. Without these secrets configured, the workflow will fail at authentication steps.
.github/workflows/create-release-lexicon.yml (2)
17-21: LGTM! Comprehensive permissions for release workflow.The permissions correctly include all necessary scopes for semantic-release to create releases, comment on issues/PRs, and use OIDC for npm provenance.
48-61: LGTM! Standard semantic-release configuration.The workflow correctly uses semantic-release with the necessary plugins and environment variables. The dry-run mode support via workflow input is a good safety feature.
.github/workflows/dryrun-release-ci-lexicon.yml (2)
38-40: LGTM! Consistent prerelease config handling.The conditional config swap is consistent with the prerelease workflow and correctly handles PR branches.
46-46: LGTM! Hardcoded dry-run mode for PR validation.Correctly hardcoded to
truefor PR validation, preventing accidental publishes from pull requests.PUBLISHING.md (1)
1-89: LGTM! Comprehensive publishing documentation.The documentation clearly explains the publishing process, prerequisites, and version management. It correctly references the workflows and explains the semantic-release behavior.
.releaserc.prerelease.yaml (1)
1-12: Semantic-release plugins are properly configured.The plugins are correctly specified in the
extra_pluginsparameter of all three GitHub Actions workflows (create-prerelease-lexicon.yml, create-release-lexicon.yml, and dryrun-release-ci-lexicon.yml) that use the cycjimmy/semantic-release-action. They will be installed at runtime by the GitHub Actions workflow, so no local installation in package.json is required.package.json (1)
6-6: Remove or update the inconsistentmainfield in package.json.The
mainfield points to./types/index.js, but the repository'spackage.jsonalready has anexportsfield that correctly points to./types/index.ts. Sincenpm run gen-apigenerates TypeScript files (not JavaScript), and theexportsfield takes precedence in modern Node.js, the legacymainfield creates an unnecessary inconsistency. Either removemainentirely or update it to match theexportsfield.Likely an incorrect or invalid review comment.
Without this patch, the package cannot be automatically published to npm. Manual publishing requires local setup and manual version management, which is error-prone and time-consuming. This patch solves the problem by adding a complete CI/CD pipeline that: - Creates three GitHub Actions workflows for manual release, prerelease, and PR validation - Configures semantic-release for automatic version management based on conventional commits - Fixes package.json entry points to correctly reference types/index.ts - Updates .npmignore to include lexicons/ in published package - Adds PUBLISHING.md documentation for maintainers The workflows are manually triggered via workflow_dispatch to give maintainers full control over when releases are published. The pipeline ensures all auto-generated TypeScript types are included in the published package. Co-authored-by: Auto <[email protected]>
aspiers
force-pushed
the
publish-pipeline
branch
from
73b5bfc to
00b19ba
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
.github/workflows/create-prerelease-lexicon.yml (2)
50-63: Configuration looks correct.The semantic-release action is properly configured with dry-run support and necessary tokens.
Note: Most of the
extra_plugins(commit-analyzer,release-notes-generator,github,npm) are already included by default in semantic-release. Only@semantic-release/changelogis truly an extra. This redundancy is harmless but could be trimmed for clarity if desired.
65-71: Remove or implement this placeholder step.The step name "Do something when a new release published" and the body (only echoing version info) suggest this is a placeholder. Either:
- Remove it if no post-release actions are needed, or
- Implement actual functionality (e.g., Slack notifications, deployment triggers)
If keeping for debugging, consider renaming to "Log release version" for clarity.
- - name: Do something when a new release published + - name: Log release version if: steps.semantic.outputs.new_release_published == 'true' run: | - echo ${{ steps.semantic.outputs.new_release_version }} - echo ${{ steps.semantic.outputs.new_release_major_version }} - echo ${{ steps.semantic.outputs.new_release_minor_version }} - echo ${{ steps.semantic.outputs.new_release_patch_version }} + echo "Released version: ${{ steps.semantic.outputs.new_release_version }}"
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
.github/workflows/create-prerelease-lexicon.yml(1 hunks).github/workflows/create-release-lexicon.yml(1 hunks).github/workflows/dryrun-release-ci-lexicon.yml(1 hunks).npmignore(0 hunks).releaserc.prerelease.yaml(1 hunks).releaserc.yaml(1 hunks)PUBLISHING.md(1 hunks)README.md(1 hunks)package.json(1 hunks)
💤 Files with no reviewable changes (1)
- .npmignore
✅ Files skipped from review due to trivial changes (1)
- .releaserc.yaml
🚧 Files skipped from review as they are similar to previous changes (6)
- .releaserc.prerelease.yaml
- .github/workflows/dryrun-release-ci-lexicon.yml
- README.md
- .github/workflows/create-release-lexicon.yml
- PUBLISHING.md
- package.json
🧰 Additional context used
📓 Path-based instructions (1)
!(types)/**/*.{js,ts,tsx,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
Run
npm run formatwith Prettier before committing to ensure consistent code formatting
Files:
.github/workflows/create-prerelease-lexicon.yml
🧠 Learnings (2)
📓 Common learnings
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 34
File: lexicons/org/hypercerts/claim/evaluation.json:45-63
Timestamp: 2025-12-15T10:13:17.689Z
Learning: For the hypercerts-lexicon repository, CI automatically runs `npm run gen-api` and `npm run check` to regenerate TypeScript types and validate lexicon definitions, so manual reminders about running these commands are not needed in code reviews.
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to !(types)/**/*.{js,ts,tsx,json,md} : Run `npm run format` with Prettier before committing to ensure consistent code formatting
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-15T17:53:11.862Z
Learning: Applies to lexicons/**/*.json : Run `npm run check` before committing to validate lexicon syntax and ensure valid lexicon definitions
📚 Learning: 2025-12-15T10:13:17.689Z
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 34
File: lexicons/org/hypercerts/claim/evaluation.json:45-63
Timestamp: 2025-12-15T10:13:17.689Z
Learning: For the hypercerts-lexicon repository, CI automatically runs `npm run gen-api` and `npm run check` to regenerate TypeScript types and validate lexicon definitions, so manual reminders about running these commands are not needed in code reviews.
Applied to files:
.github/workflows/create-prerelease-lexicon.yml
🔇 Additional comments (5)
.github/workflows/create-prerelease-lexicon.yml (5)
1-10: LGTM!The workflow trigger configuration is well-structured. The
workflow_dispatchtrigger with adry_runboolean input provides good control for maintainers to test releases before publishing.
12-19: LGTM!Permissions are correctly scoped. The
id-token: writefor npm provenance andstagingenvironment isolation are good security practices.
21-32: LGTM!Excellent documentation in the comments explaining why
fetch-depth: 0is required. Thepersist-credentials: falseis correct when using a custom PAT.
34-44: LGTM!Node.js 20 LTS with caching,
npm cifor reproducible installs, and linting before release are all best practices.
46-48: Verify the conditional prerelease config logic.This step only applies the prerelease configuration when NOT on
main. For a staging/prerelease workflow, this may be counterintuitive—if triggered frommain, it would use the regular release config instead of prerelease.Is this intentional? If the workflow should always produce prereleases regardless of branch, consider removing the condition.
Without this patch, the package cannot be automatically published to npm. Manual publishing requires local setup and manual version management, which is error-prone and time-consuming.
This patch solves the problem by adding a complete CI/CD pipeline that:
prerelease, and PR validation
based on conventional commits
types/index.ts
The workflows are manually triggered via workflow_dispatch to give maintainers full control over when releases are published. The pipeline ensures all auto-generated TypeScript types are included in the published package.
Co-authored-by: Cursor [email protected]
Summary by CodeRabbit
New Features
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.