Publish a developer package to the GitHub npm registry with GitHub Actions

.github/workflows/publish-dev-package.yml

@@ -0,0 +1,20 @@
+name: "Publish a developer package to GitHub npm registry"
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish-dev:
+    uses: ./.github/workflows/publish-package.yml
+
+    with:
+      npm-registry-url: "https://npm.pkg.github.com"
+
+    secrets:
+      npm-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-package.yml

@@ -0,0 +1,72 @@
+name: "Publish a package to a specified npm registry"
+
+on:
+  workflow_call:
+    inputs:
+      npm-registry-url:
+        description: "URL of the npm registry to publish to; e.g., https://npm.pkg.github.com for GitHub Packages"
+        type: string
+        required: true
+
+    secrets:
+      npm-token:
+        description: "Token that is allowed to publish to the npm registry; e.g., secrets.GITHUB_TOKEN for GitHub Packages"
+        required: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  node-version: 22
+  pnpm-version: 10
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get short commit hash
+        id: commit-hash
+        run: echo "short-commit-hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      # appends the short commit hash to the version number
+      # 1. reads the package.json file
+      # 2. replaces the version and saves it in the package.json
+      - name: Read package information
+        id: package-info
+        # uses the exact commit to prevent harmful updates
+        uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
+        with:
+          path: package.json
+      - name: Append short commit hash to the version
+        # uses the exact commit to prevent harmful updates
+        uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
+        with:
+          path: package.json
+          version: ${{ steps.package-info.outputs.version }}-${{ steps.commit-hash.outputs.short-commit-hash }}
+
+      - name: Install pnpm ${{ env.pnpm-version }}
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.pnpm-version }}
+
+      - name: Setup Node.js ${{ env.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.node-version }}
+          cache: pnpm
+          registry-url: ${{ inputs.npm-registry-url }}
+          scope: "@codemonger-io"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # the build script is executed by the prepare script
+      - name: Build and publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.npm-token }}
+        run: pnpm publish --no-git-checks

README.ja.md

@@ -12,6 +12,40 @@
 npm install https://github.com/codemonger-io/mapping-template-compose.git#v0.2.0
 ```
 
+### GitHub Packagesからインストールする
+
+`main`ブランチにコミットがプッシュされるたびに、*開発者用パッケージ*がGitHub Packagesの管理するnpmレジストリにパブリッシュされます。
+*開発者用パッケージ*のバージョンは次のリリースバージョンにハイフン(`-`)と短いコミットハッシュをつなげものになります。例、`0.2.0-abc1234` (`abc1234`はパッケージをビルドするのに使ったコミット(*スナップショット*)の短いコミットハッシュ)。
+*開発者用パッケージ*は[こちら](https://github.com/codemonger-io/mapping-template-compose/pkgs/npm/mapping-template-compose)にあります。
+
+#### GitHubパーソナルアクセストークンの設定
+
+*開発者用パッケージ*をインストールするには、最低限`read:packages`スコープの**クラシック**GitHubパーソナルアクセストークン(PAT)を設定する必要があります。
+以下、簡単にPATの設定方法を説明します。
+より詳しくは[GitHubのドキュメント](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)をご参照ください。
+
+PATが手に入ったら以下の内容の`.npmrc`ファイルをホームディレクトリに作成してください。
+
+```sh
+//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
+```
+
+`$YOUR_GITHUB_PAT`はご自身のPATに置き換えてください。
+
+プロジェクトのルートディレクトリに以下の内容の`.npmrc`ファイルを作成してください。
+
+```sh
+@codemonger-io:registry=https://npm.pkg.github.com
+```
+
+これで以下のコマンドで*開発者用パッケージ*をインストールできます。
+
+```sh
+npm install @codemonger-io/mapping-template-compose@0.2.0-abc1234
+```
+
+`abc1234`はインストールしたい*スナップショット*の短いコミットハッシュに置き換えてください。
+
 ## 動機
 
 Amazon API Gatewayのマッピングテンプレートを記述するのを面倒くさいと感じたことはありますか?

README.md

@@ -12,6 +12,40 @@ This library is especially powerful if you combine it with [AWS Cloud Developmen
 npm install https://github.com/codemonger-io/mapping-template-compose.git#v0.2.0
 ```
 
+### Installing from GitHub Packages
+
+Every time commits are pushed to the `main` branch, a _developer package_ is published to the npm registry managed by GitHub Packages.
+A _developer package_ bears the next release version number but followed by a dash (`-`) plus the short commit hash; e.g., `0.2.0-abc1234` where `abc1234` is the short commit hash of the commit used to build the package (_snapshot_).
+You can find _developer packages_ [here](https://github.com/codemonger-io/mapping-template-compose/pkgs/npm/mapping-template-compose).
+
+#### Configuring a GitHub personal access token
+
+To install a _developer package_, you need to configure a **classic** GitHub personal access token (PAT) with at least the `read:packages` scope.
+Below briefly explains how to configure a PAT.
+Please refer to the [GitHub documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) for more details.
+
+Once you have a PAT, please create a `.npmrc` file in your home directory with the following content:
+
+```sh
+//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
+```
+
+Please replace `$YOUR_GITHUB_PAT` with your PAT.
+
+In the root directory of your project, please create a `.npmrc` file with the following content:
+
+```sh
+@codemonger-io:registry=https://npm.pkg.github.com
+```
+
+Then you can install a _developer package_ with the following command:
+
+```sh
+npm install @codemonger-io/mapping-template-compose@0.2.0-abc1234
+```
+
+Please replace `abc1234` with the short commit hash of the _snapshot_ you want to install.
+
 ## Motivation
 
 Have you ever felt that describing mapping templates for Amazon API Gateway is cumbersome?

package.json

@@ -7,7 +7,8 @@
   "files": [
     "dist/index.js",
     "dist/index.js.map",
-    "dist/index.d.ts"
+    "dist/index.d.ts",
+    "README.ja.md"
   ],
   "scripts": {
     "build": "rimraf dist && rollup -c && api-extractor run --local",