diff --git a/.github/workflows/publish-dev-package.yml b/.github/workflows/publish-dev-package.yml new file mode 100644 index 0000000..60d0b14 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml new file mode 100644 index 0000000..7cf0a46 --- /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 diff --git a/README.ja.md b/README.ja.md index 4cc9cf0..1e49b4e 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? 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",