GitHub Packages + CircleCIによる社内ライブラリ公開・運用手順
目次
はじめに
こんにちは。フロントエンドエンジニア兼デザイナーのKimuraです。
企業で開発するにあたり、外部に非公開の社内ライブラリを作ることはよくあると思います。これまでアトラスではGit submodule経由で社内ライブラリを管理してきましたが、この方法には以下の問題点がありました。
- バージョン管理が曖昧となる
- npmの管理外となる
- CI/CD環境上で参照するための設定が少々複雑
これらの問題点を解決するため、社内ライブラリ管理をGitHub Packages経由に変更し、運用方法も含めて再整備を行いました。本記事では設定方法と運用の例を記載します。ライブラリの使用言語はJavaScriptを前提とします。
GitHub Packagesとは
GitHub Packagesは、GitHubが提供するパッケージ管理サービスです。
プライベートリポジトリに対してGitHub Packagesを利用することで、社内のみに公開したいライブラリをnpmで管理することが可能となります。
パブリックリポジトリの場合、ストレージと通信量は無制限に利用できますが、プライベートリポジトリでは契約しているプランによって制限が異なります。もしプラン内の上限に収まらない場合は、追加購入も可能です。
CI/CDツールによるパッケージ公開を構築する
今回はCircleCIの利用を前提に、パッケージ公開の設定を紹介します。
ただし、一般的にはGitHub Actions経由が推奨されることにご留意ください。プライベートライブラリをGitHub Packagesで公開した場合、通信量に制限がかかることを前述しましたが、2022年7月現在GitHub Actions経由の場合は無制限で通信可能です。
Personal Access Tokenの作成
まずは、GitHub上でPersonal Access Tokenを作成します。GitHubにログインしたうえでこちらへアクセスして、Generate new tokenを押下します。ログインするアカウントはトークンの管理をすることになるので、適切なアカウントを利用してください。
Select scopesのwrite:packageにチェックをつけます。その他の項目も任意の値を入力して、最下部のGenerate tokenを押下します。
画面遷移後、トークンが表示されるのでコピーします。トークンは再表示されませんので、ご注意ください。
ワークフロー設定
下記のとおり、CircleCIのワークフローを設定します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
version: 2.1 environment_node: &environment_node docker: - image: cimg/node:16.16.0 resource_class: small jobs: publish: <<: *environment_node steps: # 省略 - run: name: Set GitHub Token command: echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc - run: name: Publish command: npx can-npm-publish --verbose && npm publish || echo "Does not publish" && exit 1 workflows: version: 2 publish: jobs: - publish: filters: branches: ignore: /.*/ tags: only: /^v.[0-9]+\.[0-9]+\.[0-9]+$/ # 任意の正規表現 |
直接ライブラリ公開に関わる部分について補足で説明します。
まず、workflows内にて、正規表現に合致するタグが付与された場合のみ、publishが動作するように設定します。アトラスでは社内パッケージをv.0.0.0形式のタグで管理しておりますが、任意の正規表現に変更してください。
jobs内では、Set GitHub TokenとPublishのそれぞれを補足します。Set GitHub TokenではGitHub Packagesの認証のため、環境変数経由でPersonal Access Tokenを設定しています。Publishではcan-npm-publishというツールを利用し、package.jsonのバージョンが更新されている場合のみ公開処理を行うようにしています。
環境変数の追加
CI/CDの環境変数に、Personal Access Tokenを追加します。CircleCI上のリポジトリ初期設定をしていない場合、先行して設定する必要があります。（参考）
対象リポジトリのページで、Project Settingsボタンを押下します。
左メニューからEnvironment Variablesを選び、続いてAdd Environment Variableボタンを押下します。
情報を入力し、Add Environment Variableボタンを押下することで登録されます。ここでは、環境変数名はGITHUB_TOKENとします。
なお、CircleCIジョブ上で呼び出された場合、環境変数の値はマスキングされてログ出力されます（参考）。
対象リポジトリに公開設定を適用する
package.json変更
次は公開対象のリポジトリに対して、公開設定を適用します。まず、package.jsonにてprivateをfalseに設定します。
|
1 |
"private": false, |
続いて、ビルド設定を変更します。prepublishOnlyに設定されたコマンドは、npm publish実行時に自動実行されます。buildには、各リポジトリのビルド用コマンドを指定します。
|
1 2 3 4 5 |
"main": "dist/index.js", "scripts": { "build": "{ビルド用コマンド}" "prepublishOnly": "npm run build" }, |
対象リポジトリの動作の前提となるライブラリがある場合、依存先としてpeerDependenciesを指定します。以下はReactに依存している場合の例です。
|
1 2 3 4 |
"peerDependencies": { "react": "^18.2.0", "react-dom": "^18.2.0", }, |
最後に、公開設定に必要な項目を書き換えます。versionは適切な値としてください。
|
1 2 3 4 5 6 7 8 9 |
"name": "@{オーガニゼーション名}/{npmパッケージ名}", "version": "1.0.0", "repository": { "type": "git", "url": "git://github.com:{オーガニゼーション名}/{リポジトリ名}.git" }, "publishConfig": { "registry":"https://npm.pkg.github.com/{オーガニゼーション名}" }, |
実際にリリースされるかテストする
Pull Requestをリリース用ブランチにマージする
まず、package.jsonの更新を含むブランチを、リリース用ブランチ（masterなど）にマージします。
2回目以降の場合、versionが適切な値に更新されていることを確認してください。対象バージョンが公開済の場合、上書きでの公開処理は行われません。
GitHubの画面上からリリースノートを作成する
GitHub上でリリースノートを作成し、同時にリリース用ブランチへのタグ付けを行います。
初回の場合は、対象リポジトリのトップページからCreate a new releaseを押下します。
既にリリースノートが存在する場合は、対象リポジトリのトップページからReleasesを押下し、続いてDraft a new releaseを押下します。
Choose a tagにはCircleCI側で指定した正規表現に合致するタグ名（例ではv.1.0.0）を入力し、Create new tag:〜を選択します。
Targetには、リリース用ブランチを指定します。初期値はデフォルトブランチなので、リリース用ブランチが異なる場合は選択しなおす必要があります。
その他の項目には任意の内容を入力して、下部にあるPublish releaseを押下します。これにより、Targetで選択したブランチにタグ付けが行われます。
結果確認
CircleCIジョブの完了後、GitHubのトップページ上でライブラリが公開されていることを確認できます。
ライブラリを別の社内リポジトリから参照する
公開まで完了したので、ライブラリを参照したい社内リポジトリ側に参照設定を行います。
.npmrc設定追加
リポジトリの直下に.npmrcを作成します。既に存在する場合は行を追加します。
|
1 |
@{オーガニゼーション名}:registry=https://npm.pkg.github.com |
インストール
通常のnpmパッケージと同様に、インストールを行います。
|
1 |
npm install @{オーガニゼーション名}/{npmパッケージ名} |
別の社内リポジトリからCI/CDツール経由で参照する
CI/CDツール経由でのパッケージ参照には、追加設定が必要です。ローカルからは参照を確認できている前提で、設定追加箇所を記載します。
Personal Access Tokenの作成 & 環境変数の追加
手順は前述した内容と同じですが、権限はread:packagesのみにチェックします。
また、参照する側の社内リポジトリに対して、GITHUB_TOKENという環境変数を登録しておきます。
認証設定の追加
.circleci/config.yml内にて、npm installの前に下記を追加します。
|
1 2 3 |
run: name: Set GitHub Token command: echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc |
ローカルでは自身のGitHubアカウント経由で取得するため、オーガニゼーションのプライベートパッケージにアクセスすることができます。上記は、CIマシン上で同様の権限を利用するために追加しています。
設定は以上です。この状態でジョブが動くと、正常終了となるはずです。
おわりに
GitHub Packages + CircleCIによる社内ライブラリの公開・運用手順をご紹介しました。今回紹介した内容以外にも、「パッケージ公開したことが分かりづらい」という課題を解消するため、Slack通知を組み込むといった施策も行っております。
なお、構築にあたって以下の記事を参考にさせていただきました。お礼申し上げます。
