From 3a94bc8668dee6058c06a45e3cac1bf882c4c7df Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Sun, 18 May 2025 10:50:37 +0900 Subject: [PATCH 1/6] feat(gha): publish developer package Introduces a GitHub Actions workflow `publish-dev-package` which publishes a developer package to the GitHub npm registry when commits are pushed to the `main` branch. A developer package bears the target release version but followed by the short commit hash of the commit used to build the package. The actual operations are done in `publish-package.yml`. The workflow is also triggered by the `issue/2-gha-publish-dev` branch for experiments. But this trigger must be removed when experiments are completed. --- .github/workflows/publish-dev-package.yml | 21 +++++++ .github/workflows/publish-package.yml | 72 +++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 .github/workflows/publish-dev-package.yml create mode 100644 .github/workflows/publish-package.yml diff --git a/.github/workflows/publish-dev-package.yml b/.github/workflows/publish-dev-package.yml new file mode 100644 index 0000000..353a470 --- /dev/null +++ b/.github/workflows/publish-dev-package.yml @@ -0,0 +1,21 @@ +name: "Publish a developer package to GitHub npm registry" + +on: + push: + branches: + - main + - issue/2-gha-publish-dev # TODO: remove after testing + +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 }} diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml new file mode 100644 index 0000000..bebedee --- /dev/null +++ b/.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 From 21a402d779ddcdd065c9ebf546b0ef67d48902ca Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Sun, 18 May 2025 10:59:14 +0900 Subject: [PATCH 2/6] fix(gha): wrong short commit hash output name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `short_commit_hash` → `short-commit-hash`. --- .github/workflows/publish-package.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml index bebedee..7cf0a46 100644 --- a/.github/workflows/publish-package.yml +++ b/.github/workflows/publish-package.yml @@ -31,7 +31,7 @@ jobs: - name: Get short commit hash id: commit-hash - run: echo "short_commit_hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT + 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 From f72be5b1f0ad5916f524bcb347e446833c867eb2 Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Sun, 18 May 2025 13:19:31 +0900 Subject: [PATCH 3/6] docs: update README for how to install developer package --- README.ja.md | 34 ++++++++++++++++++++++++++++++++++ README.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/README.ja.md b/README.ja.md index 4cc9cf0..cdcdfb5 100644 --- a/README.ja.md +++ b/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のマッピングテンプレートを記述するのを面倒くさいと感じたことはありますか? diff --git a/README.md b/README.md index 4150dca..2a18735 100644 --- a/README.md +++ b/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? From a4018e1e930a2eadc89be1c4b67a38c371142d0d Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Mon, 19 May 2025 01:06:50 +0900 Subject: [PATCH 4/6] chore: bundle README.ja.md into package --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 2543247..496006d 100644 --- a/package.json +++ b/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", From e954f0e387925a66f513a81a20098cb5bf7a7e1d Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Mon, 19 May 2025 01:15:34 +0900 Subject: [PATCH 5/6] docs: update README.ja.md Fixes an awkward Japanese term. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.ja.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.ja.md b/README.ja.md index cdcdfb5..1e49b4e 100644 --- a/README.ja.md +++ b/README.ja.md @@ -20,7 +20,7 @@ npm install https://github.com/codemonger-io/mapping-template-compose.git#v0.2.0 #### GitHubパーソナルアクセストークンの設定 -*開発者用パッケージ*をインストールするには、最低限`read:packages`スコープの**クラッシック**GitHubパーソナルアクセストークン(PAT)を設定する必要があります。 +*開発者用パッケージ*をインストールするには、最低限`read:packages`スコープの**クラシック**GitHubパーソナルアクセストークン(PAT)を設定する必要があります。 以下、簡単にPATの設定方法を説明します。 より詳しくは[GitHubのドキュメント](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)をご参照ください。 From 70abf7d9dde3ca7208bb571b5fa2a5ddfe3f1536 Mon Sep 17 00:00:00 2001 From: Kikuo Emoto Date: Mon, 19 May 2025 01:17:57 +0900 Subject: [PATCH 6/6] chore(gha): remove trigger for experiments --- .github/workflows/publish-dev-package.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/publish-dev-package.yml b/.github/workflows/publish-dev-package.yml index 353a470..60d0b14 100644 --- a/.github/workflows/publish-dev-package.yml +++ b/.github/workflows/publish-dev-package.yml @@ -4,7 +4,6 @@ on: push: branches: - main - - issue/2-gha-publish-dev # TODO: remove after testing permissions: contents: read