GitHub Packages をサクッとつかってみる

1. はじめに

npm パッケージを公開する際、手作業でのバージョン管理や公開作業は煩雑になりがちです。GitHub Packages と GitHub Actions を組み合わせることで、リリース作成をトリガーにした自動公開パイプラインを構築できます。この記事では、実際の手順を通じて、テストから公開までを自動化する方法を解説します。

2. 全体の流れ

リリースを作成すると、自動的にテストが実行され、成功した場合のみパッケージが公開されます。

3. リポジトリとパッケージの準備

3.1. リポジトリの作成とクローン

まず、GitHub上で新しいリポジトリを作成します。この際、Node用の.gitignoreを追加しておくと便利です。

git clone https://github.com/yamada-taro/my-package.git
cd my-package

3.2. パッケージの初期化

基本的なコードを作成します。

index.js

console.log("Hello, World!");

次に、npmパッケージとして初期化します。

npm init

初期化ウィザードでは、以下のように設定します。

• package name: @yamada-taro/my-package（@ユーザー名/リポジトリ名の形式）
• test command: exit 0

この設定により、package.jsonが生成されます。スコープ付きのパッケージ名を使用することで、GitHub Packagesとの統合がスムーズになります。

3.3. 初回コミット

依存関係のロックファイルを生成し、すべてをコミットします。

npm install
git add index.js package.json package-lock.json
git commit -m "initialize npm package"
git push

4. GitHub Actionsワークフローの構築

4.1. ワークフローファイルの作成

.github/workflowsディレクトリを作成し、その中にrelease-package.ymlを配置します。

mkdir -p .github/workflows

release-package.yml

name: Node.js Package

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://npm.pkg.github.com/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

4.2. ワークフローの構成要素

このワークフローは2つのジョブで構成されています。

buildジョブは品質検証を行います。npm ciで依存関係をクリーンインストールし、npm testでテストを実行します。npm ciを使用することで、package-lock.jsonに記録された正確なバージョンでの動作を保証できます。

publish-gprジョブは、buildジョブの成功を前提に実行されます（needs: build）。重要なポイントは以下の通りです。

• permissionsセクションで必要な権限を明示的に指定
• registry-urlでGitHub Packagesのレジストリを指定
• NODE_AUTH_TOKENにGITHUB_TOKENを設定して認証

GITHUB_TOKENはGitHub Actionsによって自動的に提供されるため、追加の設定は不要です。

3. レジストリの設定

npmにパッケージの公開先を伝える必要があります。2つの方法があります。

方法1: .npmrcファイルを使用

プロジェクトルートに.npmrcを作成します。

.npmrc

@yamada-taro:registry=https://npm.pkg.github.com

5.2. 方法2: package.jsonで設定

package.jsonにpublishConfigを追加します。

{
  "name": "@yamada-taro/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "@yamada-taro:registry": "https://npm.pkg.github.com"
  }
}

どちらの方法でも、スコープ（@yamada-taro）に対してGitHub Packagesのレジストリを指定しています。

5.3. 設定のコミット

git add .github/workflows/release-package.yml
git add .npmrc  # または package.json
git commit -m "workflow to publish package"
git push

6. リリースとパッケージ公開

6.1. リリースの作成

GitHubのリポジトリページで、以下の手順でリリースを作成します。

1. リポジトリの「Code」タブに移動
2. 右側のサイドバーから「Releases」をクリック
3. 「Create a new release」をクリック
4. タグバージョン（例: v1.0.0）とリリースノートを入力
5. 「Publish release」をクリック

リリースを作成すると、ワークフローが自動的にトリガーされます。

6.2. ワークフローの実行確認

「Actions」タブでワークフローの実行状況を確認できます。テストが成功すれば、パッケージがGitHub Packagesに公開されます。

6.3. 公開されたパッケージの確認

リポジトリページの右側サイドバーにある「Packages」セクションから、公開されたパッケージを確認できます。

5. パッケージのインストールと利用

公開されたパッケージは、他のプロジェクトで依存関係として利用できます。

認証の設定

GitHub Packagesからインストールするには、個人アクセストークンが必要です。プロジェクトの.npmrcに以下を追加します。

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
@yamada-taro:registry=https://npm.pkg.github.com

7.2. インストール

npm install @yamada-taro/my-package

これで、通常のnpmパッケージと同様に使用できます。

8. この仕組みの利点

リリース作成という単一のアクションで、テスト実行から公開までが自動化されます。テストが失敗した場合はパッケージは公開されず、品質を担保できます。GitHub Actionsのログにより、実行履歴も追跡可能です。

9. さらなる発展

今回紹介したのは基本的なワークフローです。このワークフローは、複数のレジストリへの同時公開や、プルリクエストマージ時のトリガーなど、さまざまな形で拡張できます。GitHub PackagesとGitHub Actionsを組み合わせることで、アプリケーション開発のほぼすべてのプロセスを自動化できます。

10. まとめ

GitHub PackagesとGitHub Actionsを使った自動公開パイプラインは、以下の要素で構成されます。

1. スコープ付きパッケージ名の設定（@ユーザー名/パッケージ名）
2. リリース作成をトリガーとするワークフローの定義
3. buildジョブによるテスト実行
4. publish-gprジョブによるパッケージ公開
5. レジストリ設定による公開先の指定

この仕組みにより、品質を担保しながら、効率的なパッケージ管理が実現できます。リリース作成という開発者にとって自然な操作をトリガーとすることで、追加の学習コストを最小限に抑えられる点も利点です。

パッケージ管理の自動化は、チーム開発における一貫性と信頼性の向上に直結します。ぜひ、実際のプロジェクトで試してみてください。