Skip to content

Commit fc7e7de

Browse files
kikuomaxkikuomax
authored
Publish a developer package by GitHub Actions (#25)
* feat(gha): build package Introduces the following workflows: - `publish-dev-package`: publishes a developer package when commits are pushed to the `dev` branch. Invokes the `publish-package` workflow. - `publish-package`: implements the process to publish a package. Designed for the GitHub npm registry for now. * feat(gha): append short commit hash to version The `publish-package` workflow appends the short commit hash to the version for a developer package. * feat(gha): publish developer package The `publish-package` workflow publishes the built package to a specified npm registry. The caller has to specify the following parameters: - `npm-registry-url`: URL of the npm registry to publish to. - `npm-token`: token that is allowed to publish to the npm registry The `publish-dev-package` workflow configures the above parameters for the GitHub npm registry. * fix(gha): unclean working tree error on publish Works around the problem that the `pnpm publish` command failed due to an unclean git working copy. As the short commit hash is appended to the version of a developer package, the working copy is always unclean. Adds the `--no-git-checks` option to the `pnpm publish` command as a workaround. * chore: include README.ja.md in package * chore(gha): specify the scope of the package * chore: add repository to package.json * chore(gha): change trigger branch: dev → main The `publish-dev-package` workflow changes the trigger branch from `dev` to `main`. I decided not to duplicate the `main` branch as `dev`. When it would come to publishing to the official npm registry, we should consider other triggers: e.g. creation of a release. * docs: update README Explains how to install a developer package from the GitHub npm registry.
1 parent 749f5c1 commit fc7e7de

File tree

5 files changed

+166
-1
lines changed

5 files changed

+166
-1
lines changed

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Publish a developer package
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
packages: write
10+
contents: read
11+
12+
jobs:
13+
publish:
14+
uses: ./.github/workflows/publish-package.yml
15+
16+
with:
17+
npm-registry-url: 'https://npm.pkg.github.com'
18+
19+
secrets:
20+
npm-token: ${{ secrets.GITHUB_TOKEN }}

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Publish a package
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
npm-registry-url:
7+
description: 'URL of the npm registry to publish to; e.g., https://npm.pkg.github.com for GitHub Packages'
8+
type: string
9+
required: true
10+
11+
secrets:
12+
npm-token:
13+
description: 'Token that is allowed to publish to the npm registry; e.g., GITHUB_TOKEN for GitHub Packages'
14+
required: true
15+
16+
env:
17+
node-version: 22
18+
pnpm-version: 10
19+
20+
permissions:
21+
packages: write
22+
contents: read
23+
24+
jobs:
25+
build-dist:
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
32+
- name: Get short commit hash
33+
id: commit-hash
34+
run: echo "short-commit-hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
35+
36+
- name: Install pnpm ${{ env.pnpm-version }}
37+
uses: pnpm/action-setup@v4
38+
with:
39+
version: ${{ env.pnpm-version }}
40+
41+
- name: Setup Node.js ${{ env.node-version }}
42+
uses: actions/setup-node@v4
43+
with:
44+
node-version: ${{ env.node-version }}
45+
cache: 'pnpm'
46+
registry-url: ${{ inputs.npm-registry-url }}
47+
scope: '@codemonger-io'
48+
49+
# appends the short commit hash to the version
50+
# 1. reads package information
51+
# 2. appends the short commit hash to the version and writes it back
52+
- name: Extract package information
53+
id: package-info
54+
# uses the exact commit to prevent harmful updates
55+
uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
56+
with:
57+
path: package.json
58+
- name: Append short commit hash to the version
59+
# uses the exact commit to prevent harmful updates
60+
uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
61+
with:
62+
path: package.json
63+
version: ${{ steps.package-info.outputs.version }}-${{ steps.commit-hash.outputs.short-commit-hash }}
64+
65+
- name: Install dependencies
66+
run: pnpm install
67+
68+
# the build script is executed by the prepare script
69+
- name: Build and publish
70+
env:
71+
NODE_AUTH_TOKEN: ${{ secrets.npm-token }}
72+
run: pnpm publish --no-git-checks

‎README.ja.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,40 @@ npm install https://github.com/codemonger-io/cdk-rest-api-with-spec.git#v0.3.0
3030

3131
CDK v2プロジェクトで使っている限り、これらを別途インストールする必要はないはずです。
3232

33+
### GitHub Packagesからインストールする
34+
35+
`main`ブランチにコミットがプッシュされるたびに、開発者用パッケージがGitHub Packagesの管理するnpmレジストリにパブリッシュされます。
36+
開発者用パッケージのバージョンは次のリリースバージョンとハイフン(`-`)と短いコミットハッシュををつなげたもので表現されます。例、`0.3.0-abc1234` (`abc1234`はパッケージをビルドするのに使ったコミット(*スナップショット*)のコミットハッシュ)。
37+
開発者用パッケージは[こちら](https://github.com/codemonger-io/cdk-rest-api-with-spec/pkgs/npm/cdk-rest-api-with-spec)にあります。
38+
39+
#### GitHubパーソナルアクセストークンの設定
40+
41+
開発者用パッケージをインストールするには、最低限`read:packages`スコープの**クラッシック**GitHubパーソナルアクセストークン(PAT)を設定する必要があります。
42+
以下、簡単にPATの設定方法を説明します。
43+
より詳しくは[GitHubのドキュメント](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)をご参照ください。
44+
45+
PATが手に入ったら以下の内容の`.npmrc`ファイルをホームディレクトリに作成してください。
46+
47+
```
48+
//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
49+
```
50+
51+
`$YOUR_GITHUB_PAT`はご自身のPATに置き換えてください。
52+
53+
プロジェクトのルートディレクトリに以下の内容の`.npmrc`ファイルを作成してください。
54+
55+
```
56+
@codemonger-io:registry=https://npm.pkg.github.com
57+
```
58+
59+
これで以下のコマンドで開発者パッケージをインストールできます。
60+
61+
```sh
62+
npm install @codemonger-io/cdk-rest-api-with-spec@0.3.0-abc1234
63+
```
64+
65+
`abc1234`はインストールしたい*スナップショット*の短いコミットハッシュに置き換えてください。
66+
3367
## 始める
3468

3569
[`aws_apigateway.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html)の代わりに[`RestApiWithSpec`](./api-docs/markdown/cdk-rest-api-with-spec.restapiwithspec.md)をインスタンス化してください。

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,40 @@ This library is supposed to be used in a CDK v2 project, so it does not include
3030

3131
As long as you are working on a CDK v2 project, you should not have to separately install them.
3232

33+
### Installing from GitHub Packages
34+
35+
Every time commits are pushed to the `main` branch, a developer package is published to the npm registry managed by GitHub Packages.
36+
The version of a developer package is represented by the next release version followed by a dash (`-`) plus the short commit hash; e.g., `0.3.0-abc1234` where `abc1234` is the short commit hash of the commit used to build the package (*snapshot*).
37+
You can find developer packages [here](https://github.com/codemonger-io/cdk-rest-api-with-spec/pkgs/npm/cdk-rest-api-with-spec).
38+
39+
#### Configuring GitHub personal access token
40+
41+
To install a developer package, you need to configure a **classic** GitHub personal access token (PAT) with at least the `read:packages` scope.
42+
Below briefly explains how to configure a PAT.
43+
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.
44+
45+
Once you have a PAT, please create a `.npmrc` file in your home directory with the following content,
46+
47+
```
48+
//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
49+
```
50+
51+
Please replace `$YOUR_GITHUB_PAT` with your PAT.
52+
53+
In the root directory of your project, please create a `.npmrc` file with the following content,
54+
55+
```
56+
@codemonger-io:registry=https://npm.pkg.github.com
57+
```
58+
59+
Then you can install a developer package with the following command,
60+
61+
```sh
62+
npm install @codemonger-io/cdk-rest-api-with-spec@0.3.0-abc1234
63+
```
64+
65+
Please replace `abc1234` with the short commit hash of the *snapshot* you want to install.
66+
3367
## Getting started
3468

3569
Please instantiate [`RestApiWithSpec`](./api-docs/markdown/cdk-rest-api-with-spec.restapiwithspec.md) instead of [`aws_apigateway.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html).

‎package.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,17 @@
22
"name": "@codemonger-io/cdk-rest-api-with-spec",
33
"version": "0.3.0",
44
"description": "Describe Amazon API Gateway and OpenAPI at once with CDK",
5+
"repository": {
6+
"type": "git",
7+
"url": "https://github.com/codemonger-io/cdk-rest-api-with-spec.git"
8+
},
59
"main": "./dist/index.js",
610
"typings": "./dist/index.d.ts",
711
"files": [
812
"dist/index.js",
913
"dist/index.d.ts",
10-
"dist/index.js.map"
14+
"dist/index.js.map",
15+
"README.ja.md"
1116
],
1217
"scripts": {
1318
"build": "rimraf dist && rollup -c && api-extractor run --local",

0 commit comments

Comments
 (0)