【Git・GitHub操作ガイド】第11章 GitHub Releases ＆ Packages 使い方 ｜ npmライブラリ公開とバージョン管理のベストプラクティス

「よし、最高のアプリが完成した！…でも、これってどうやってみんなに使ってもらえばいいんだろう？」

あなたが苦労して書いたそのコード、せっかくなら他の人にも使ってもらったり、未来の自分のために「完成品」として形に残しておきたくありませんか？

この記事を読み終えたとき、あなたは…

• ReleasesとPackagesの明確な違いを、自分の言葉で説明できるようになります。
• あなたが作ったツールやアプリに正式なバージョン番号を付け、世界中に公開できるようになります。
• 自分だけのプライベートなnpmライブラリを作成し、別のプロジェクトから再利用するスキルが身につきます。
• 手動でのリリース作業から解放される、自動化（GitHub Actions）への第一歩を踏み出せます。

この記事の対象読者

• 開発経験1年未満で、GitやGitHubの基本操作には慣れてきた方
• 自分の作ったツールやライブラリを他の人にも使ってもらいたいと考えている方
• 「バージョン管理」の次のステップとして、成果物の「配布」方法を学びたい方
• GitHub Actionsを使った自動化に興味があるが、何から手をつけていいか分からない方

目次

• なぜmainブランチだけでは不十分なのか？ソフトウェア配布の重要性
• GitHub Releases と Packages の違いが一目でわかる比較表
• GitHub Releases の使い方：エンドユーザーに完成品を届ける方法
• GitHub Packages の使い方：再利用可能なnpmパッケージを安全に管理・共有する
• 【ハンズオン】npmプライベートパッケージをGitHub Packagesで公開する全手順
• よくある質問（FAQ）
• 参考資料
• まとめ：明日から始めるあなたのためのネクストステップ

なぜmainブランチだけでは不十分なのか？ソフトウェア配布の重要性

開発したソフトウェアをmainブランチにマージしただけでは、あなたの素晴らしい作品はまだ”宝の持ち腐れ”かもしれません。エンドユーザーや他の開発者に「製品」として届けるまでが、ソフトウェア開発のゴールです。

この記事では、あなたのリポジトリを、完成品を並べる 「公式ストア」（GitHub Releases）と、再利用可能な部品を供給する 「パーツセンター」（GitHub Packages）に変える2つの強力な機能について、初心者にも分かりやすく解説します。

GitHub Releases と Packages の違いが一目でわかる比較表

GitHub ReleasesとGitHub Packagesは、どちらも成果物を配布するための機能ですが、対象とする相手が異なります。

そして、これらのリリース作業を自動化する鍵が、GitHub Actionsです。手動でのリリース作業はミスが多く、手間もかかりますが、Actionsを使えば、タグが作成されたタイミングで、ビルドから公開までの一連の流れを毎回完璧に実行できます。

GitHub Releases の使い方：エンドユーザーに完成品を届ける方法

内容:

Gitの 「タグ」（特定のバージョンに付ける目印） を元に、GitHub上に永続的なリリース情報ページを作成します。このページには、以下の要素を含めることができます。

• バージョン番号（タグ名）
• リリースタイトルと、Markdownで記述された詳細なリリースノート
• コンパイル済みのバイナリやインストーラーなどの「アセット（成果物）」
• ソースコードのアーカイブ（.zip / .tar.gz）
  • これは、リリースを作成した際にGitHubが自動で生成・添付してくれるファイルです。中身は、そのリリース（タグ）時点のプロジェクトの全ソースコードです。

【なぜこれが便利なの？】
あなたがアセットとして添付するコンパイル済みの実行可能ファイルとは別に、ソースコード一式が提供されることには、大きなメリットがあります。

• Gitに不慣れな人でも安心: Gitコマンド（git cloneやgit checkout）を使わなくても、特定のバージョンのソースコードをWebブラウザからワンクリックでダウンロードできます。
• 開発者にとっての利便性: ユーザーが「ソースコードも見てみたい」と思った時にすぐ入手できます。
• アーカイブとして: 特定の時点でのプロジェクトの状態を、単一のファイルとして簡単に保存できます。 注意！ このアーカイブには、.gitignore ファイルで追跡対象外に指定されているファイル（例えば、node_modules ディレクトリや .env ファイルなど）は含まれません。

利用事例:

• コマンドラインツールの実行バイナリを、Windows/macOS/Linux向けに配布したい。
• ゲームの新しいバージョンを、実行ファイルとアセットをzipで固めて公開したい。

実行手順 (ghを使う方法):

gh release createコマンドを使えば、この作業が驚くほど簡単になります。

# v1.2.3というタグを元にリリースを作成
# --generate-notesフラグで、これまでのコミット履歴からリリースノートを自動生成
# 複数のアセットを添付する場合は、--attachフラグを繰り返す
gh release create v1.2.3 \
  --generate-notes \
  --attach ./dist/app.zip \
  --attach ./dist/installer.exe

# v1.2.3というタグを元にリリースを作成
# --generate-notesフラグで、これまでのコミット履歴からリリースノートを自動生成
# 複数のアセットを添付する場合は、--attachフラグを繰り返す
gh release create v1.2.3 \
  --generate-notes \
  --attach ./dist/app.zip \
  --attach ./dist/installer.exe

このコマンド一つで、見栄えの良いリリースノートが作成され、必要なファイルが添付されたリリースが完成します。

見本：質の高いリリースノートの書き方

質の高いリリースノートは、ユーザーや他の開発者との重要なコミュニケーションツールです。gh release create --generate-notes は優れたベースを自動生成してくれますが、それをさらに分かりやすく編集することで、プロジェクトの信頼性が向上します。

以下は、フォーマルなスタイルを意識したリリースノートの見本です。

GitHub Packages の使い方：再利用可能なnpmパッケージを安全に管理・共有する

内容:

あなたのリポジトリを、各種言語のパッケージレジストリとして機能させます。GitHub Packagesはプライベートにもパブリックにも設定できるため、社内限定のライブラリ共有から、世界中の開発者に向けたオープンソースライブラリの公開まで、幅広く対応できます。

利用事例:

• 複数のプロジェクトで共通して利用する、自社独自のUIコンポーネントライブラリ（npmパッケージ）を管理したい。
• アプリケーションをコンテナ化し、そのDockerイメージをチーム内で共有したい。

実行手順 (Actionsでの自動公開):

GitHub Packagesへの公開は、GitHub Actionsと組み合わせるのが一般的です。
Actionsのワークフロー内では、secrets.GITHUB_TOKENという特別なトークンが利用できます。これは、ワークフローの実行ごとにGitHubが自動的に生成する一時的なトークンで、パスワードや個人アクセストークンをコードに直接書き込む必要がなく、安全に認証を行えます。

以下は、npmパッケージを公開するワークフローの抜粋例です。

# .github/workflows/publish.yml
# ワークフローの名前
name: Publish Package to GitHub Packages

# ワークフローが実行されるきっかけ（トリガー）
on:
  push:
    # 'v'で始まり、'数字.数字.数字'という形式のタグがプッシュされた時
    tags:
      - 'v*.*.*'

# 実行される具体的な処理（ジョブ）
jobs:
  publish:
    # ubuntu-latestという仮想環境で実行
    runs-on: ubuntu-latest
    # 処理のステップ
    steps:
      # 1. リポジトリのコードをチェックアウト（仮想環境にコピー）
      - uses: actions/checkout@v4
      # 2. Node.js環境をセットアップ
      - uses: actions/setup-node@v4
        with:
          # Node.jsのバージョン20を使用
          node-version: '20'
          # パッケージの公開先をGitHub Packagesに設定
          registry-url: 'https://npm.pkg.github.com'
            # 3. 依存関係をクリーンインストール
      # package-lock.json に基づいて高速かつ確実なインストールを行う
      - run: npm ci
      # 4. パッケージを公開
      - run: npm publish
        env:
          # 認証に必要なトークン。GitHubが自動で用意してくれる安全なもの
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# .github/workflows/publish.yml
# ワークフローの名前
name: Publish Package to GitHub Packages

# ワークフローが実行されるきっかけ（トリガー）
on:
  push:
    # 'v'で始まり、'数字.数字.数字'という形式のタグがプッシュされた時
    tags:
      - 'v*.*.*'

# 実行される具体的な処理（ジョブ）
jobs:
  publish:
    # ubuntu-latestという仮想環境で実行
    runs-on: ubuntu-latest
    # 処理のステップ
    steps:
      # 1. リポジトリのコードをチェックアウト（仮想環境にコピー）
      - uses: actions/checkout@v4
      # 2. Node.js環境をセットアップ
      - uses: actions/setup-node@v4
        with:
          # Node.jsのバージョン20を使用
          node-version: '20'
          # パッケージの公開先をGitHub Packagesに設定
          registry-url: 'https://npm.pkg.github.com'
            # 3. 依存関係をクリーンインストール
      # package-lock.json に基づいて高速かつ確実なインストールを行う
      - run: npm ci
      # 4. パッケージを公開
      - run: npm publish
        env:
          # 認証に必要なトークン。GitHubが自動で用意してくれる安全なもの
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

この設定により、v1.0.0のようなタグをプッシュするだけで、ビルド、テスト、そしてGitHub Packagesへの公開までが全自動で行われます。

【ハンズオン】npmプライベートパッケージをGitHub Packagesで公開する全手順

理論を学んだら、次は実践です！ここでは、簡単な挨拶を返すJavaScriptライブラリを作成し、GitHub Packagesにプライベートで公開、そして別のプロジェクトから利用するまでの一連の流れを体験してみましょう。

注： 以下の手順に出てくる YOUR_USERNAME は、ご自身のGitHubユーザー名に置き換えてください。

ステップ0: 準備

このハンズオンを進めるには、お使いのコンピュータに Node.js と npm がインストールされている必要があります。ターミナルで以下のコマンドを実行して、バージョンが表示されれば準備OKです。

node -v
npm -v

node -v
npm -v

Node.js と npm のインストール手順は、以下の記事で詳細に解説しています。

ステップ1: ライブラリ用のプロジェクト作成

まず、パッケージのソースコードを管理するためのリポジトリを作成します。

1. GitHub上で my-greeting-library という名前の新しいリポジトリを作成します。この時、必ず Private を選択してください。
2. 作成したリポジトリをローカルにクローンします。

git clone https://github.com/YOUR_USERNAME/my-greeting-library.git
cd my-greeting-library

git clone https://github.com/YOUR_USERNAME/my-greeting-library.git
cd my-greeting-library

3. npm プロジェクトを初期化します。

# -y を付けると、すべての質問にYesで答えてpackage.jsonを自動生成します
npm init -y

# -y を付けると、すべての質問にYesで答えてpackage.jsonを自動生成します
npm init -y

4. package-lock.json を生成します。

# この段階では依存ライブラリはないが、CI/CDで必要になるロックファイルを生成しておく
npm install

# この段階では依存ライブラリはないが、CI/CDで必要になるロックファイルを生成しておく
npm install

ステップ2: package.json の設定

package.json は、プロジェクトの情報や依存関係を定義する重要なファイルです。GitHub Packagesに公開するために、少し編集しましょう。

1. package.json を開き、name プロパティを @<あなたのGitHubユーザー名>/<リポジトリ名> の形式に変更します。これはスコープ付きパッケージと呼ばれ、GitHub Packagesでは必須です。
2. publishConfig プロパティを追加し、パッケージの公開先を指定します。
3. （任意）description や repository なども更新しておくと丁寧です。

package.json の編集例:

{
  "name": "@YOUR_USERNAME/my-greeting-library",
  "version": "1.0.0",
  "description": "A simple greeting library for the GitHub Packages hands-on.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/YOUR_USERNAME/my-greeting-library.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  },
  "keywords": [],
  "author": "YOUR_USERNAME",
  "license": "ISC"
}

{
  "name": "@YOUR_USERNAME/my-greeting-library",
  "version": "1.0.0",
  "description": "A simple greeting library for the GitHub Packages hands-on.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/YOUR_USERNAME/my-greeting-library.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  },
  "keywords": [],
  "author": "YOUR_USERNAME",
  "license": "ISC"
}

ポイント： name の @YOUR_USERNAME の部分が、パッケージが個人の所有物であることを示す「名前空間」の役割を果たします。

ステップ3: ライブラリのコード作成

次に、ライブラリ本体のコードを書きます。index.js というファイルを作成してください。

index.js:

// 挨拶を返す簡単な関数
// @param {string} [name] - 挨拶する相手の名前（任意）
// @returns {string} - 生成された挨拶メッセージ
function sayHello(name) {
  // nameが渡されなかった場合は \'World\' をデフォルト値として使用する
  const targetName = name || \'World\';
  // テンプレートリテラルを使って、動的にメッセージを組み立てる
  return `Hello, ${targetName}! Welcome to GitHub Packages!`;
}

// この関数を、require()で読み込めるように外部に公開する
module.exports = { sayHello };

// 挨拶を返す簡単な関数
// @param {string} [name] - 挨拶する相手の名前（任意）
// @returns {string} - 生成された挨拶メッセージ
function sayHello(name) {
  // nameが渡されなかった場合は \'World\' をデフォルト値として使用する
  const targetName = name || \'World\';
  // テンプレートリテラルを使って、動的にメッセージを組み立てる
  return `Hello, ${targetName}! Welcome to GitHub Packages!`;
}

// この関数を、require()で読み込めるように外部に公開する
module.exports = { sayHello };

ステップ4: 認証とパッケージの公開

いよいよパッケージを公開します。npmがあなたの代わりにGitHub Packagesへ書き込みを行うため、認証が必要です。ここでは、Personal Access Token (PAT) を使う方法を紹介します。

ここから行うのは、npmというあなたの代わりに作業してくれるアシスタントに、「あなたの代理としてGitHub Packagesという倉庫に荷物（パッケージ）を置いてきてください」とお願いするための「入館証（PAT）」を渡すようなイメージです。

1. Personal Access Token (PAT) の作成

• GitHubの Settings > Developer settings > Personal access tokens > Tokens (classic) にアクセスします。
• Generate new token > Generate new token (classic) をクリックします。
• Note に github-packages-handson など分かりやすい名前を付けます。
• Expiration（有効期限）を設定します（練習なので7日間などでOK）。
• Select scopes で write:packages にチェックを付けます。これはパッケージの書き込みに必要な権限です。（依存する read:packages や repo スコープも自動で選択されることがあります）。

【セキュリティアドバイス】（筆者の経験より）
私自身、キャリアの初期にスコープの広いPATを誤ってパブリックリポジトリにコミットしてしまい、血の気が引いた経験があります。幸いすぐに無効化して事なきを得ましたが、これは誰にでも起こりうるミスです。PATはあなたの家の「マスターキー」と同じです。絶対にコードに含めたり、安易に扱ったりしないでください。

• 有効期限は必ず設定する（練習なら1日や7日で十分です）
• スコープは常に最小限に（今回は write:packages のみでOK）
• この後のハンズオンで紹介する GITHUB_TOKEN を使うGitHub Actionsでの自動化が、現代の開発ではベストプラクティスです。

なぜなら、GITHUB_TOKEN はワークフロー実行ごとに自動生成・失効する一時的なものであり、漏洩リスクが格段に低いからです。今回はまず仕組みを理解するために手動で行いますが、実務では必ず自動化を検討してください。

• Generate token をクリックし、表示されたトークンを必ずコピーして安全な場所に保管してください。 このトークンは二度と表示されません。

1. npmへのログイン
   ターミナルで以下のコマンドを実行します。

# ユーザー名を聞かれたら、あなたのGitHubユーザー名を入力
# パスワードを聞かれたら、先ほどコピーしたPATを貼り付けます（入力内容は表示されません）
# メールアドレスを聞かれたら、あなたのGitHub登録メールアドレスを入力
npm login --registry=https://npm.pkg.github.com

# ユーザー名を聞かれたら、あなたのGitHubユーザー名を入力
# パスワードを聞かれたら、先ほどコピーしたPATを貼り付けます（入力内容は表示されません）
# メールアドレスを聞かれたら、あなたのGitHub登録メールアドレスを入力
npm login --registry=https://npm.pkg.github.com

つまずきポイント： もしGitHubアカウントで二要素認証（2FA）を有効にしている場合、ここでパスワードを入力してもログインできません。必ず先ほど作成したPATをパスワードとして使用してください。

3. パッケージの公開
   準備が整いました。以下のコマンドでパッケージを公開しましょう！

npm publish

npm publish

成功すると、+ @YOUR_USERNAME/my-greeting-library@1.0.0 のようなメッセージが表示されます。GitHubリポジトリのトップページ右側にある「Packages」セクションにも、公開したパッケージが表示されているはずです。

もし npm publish に失敗したら？
> – バージョン番号を確認: 403 Forbidden エラーが出た場合、同じバージョン番号のパッケージが既に存在している可能性があります。package.jsonの"version"を"1.0.1"のように更新してから、再度publishしてみてください。
> – スコープ名を確認: package.jsonの"name"が正しく"@YOUR_USERNAME/my-greeting-library"の形式になっているか確認しましょう。

ステップ5: 別プロジェクトからの利用

最後に、公開したライブラリを別のプロジェクトから使ってみましょう。

1. テスト用プロジェクトの準備

my-greeting-library ディレクトリの外に、新しいディレクトリを作成して移動します。

cd ..
mkdir my-test-app
cd my-test-app
npm init -y

cd ..
mkdir my-test-app
cd my-test-app
npm init -y

2. .npmrc ファイルの作成

プライベートパッケージを npm install するには、「@YOUR_USERNAME スコープのパッケージはGitHub Packagesから探してね」とnpmに教えてあげる必要があります。
package.jsonと同じ階層に.npmrc というファイルを作成し、以下の内容を記述します。

.npmrc:

@YOUR_USERNAME:registry=https://npm.pkg.github.com/

@YOUR_USERNAME:registry=https://npm.pkg.github.com/

注意： この設定は、npmがGitHubに認証するためのものではありません。認証はステップ4で完了しています。これはあくまでパッケージの場所を教えるための設定です。

3. ライブラリのインストール

以下のコマンドで、先ほど公開したライブラリをインストールします。

npm install @YOUR_USERNAME/my-greeting-library

npm install @YOUR_USERNAME/my-greeting-library

4. 動作確認
   test.js というファイルを作成し、ライブラリを呼び出してみましょう。

test.js:

// インストールしたライブラリを読み込む
const { sayHello } = require(\'@YOUR_USERNAME/my-greeting-library\');

// 関数を実行して結果を表示
console.log(sayHello(\'CodeCrafter\'));

// インストールしたライブラリを読み込む
const { sayHello } = require(\'@YOUR_USERNAME/my-greeting-library\');

// 関数を実行して結果を表示
console.log(sayHello(\'CodeCrafter\'));

ターミナルで node test.js を実行して、Hello, CodeCrafter! Welcome to GitHub Packages! と表示されれば大成功です！

お疲れ様でした！これで、あなたは自分だけのライブラリをGitHub Packagesに公開し、利用するスキルを身につけました。

よくある質問（FAQ）

Q1: Personal Access Token (PAT) と GITHUB_TOKEN の違いは何ですか？

A: 簡単に言うと、PATは「個人用の万能キー」、GITHUB_TOKENは「ワークフロー専用の使い捨てキー」 です。PATは有効期限が長く、複数の権限を持たせられるため強力ですが、漏洩時のリスクが非常に高いです。一方、GITHUB_TOKENはGitHub Actionsの実行中にのみ有効な一時的なトークンで、そのワークフローが実行されているリポジトリに対する権限しか持たないため、格段に安全です。セキュリティの観点から、自動化の際には常にGITHUB_TOKENの使用が推奨されます。

Q2: GitHub Packages の利用は無料ですか？

A: パブリックリポジトリでの利用は完全に無料です。 プライベートリポジトリの場合、ストレージ容量とデータ転送量に無料枠が設けられています（例：500MBのストレージ）。個人開発や小規模なチームであれば無料枠で十分な場合が多いですが、大規模に利用する場合は料金が発生する可能性があります。最新の料金体系は公式サイトで確認してください。

Q3: 間違ったバージョンを publish してしまいました。削除できますか？

A: 一度公開したパッケージのバージョンを完全に削除することは、原則として推奨されません。なぜなら、そのバージョンに依存している他のプロジェクトがビルドできなくなる「破壊的変更」を引き起こす可能性があるからです。どうしても削除したい場合は、GitHubのパッケージ設定画面から削除できますが、細心の注意が必要です。代わりに、npm deprecateコマンドでそのバージョンを「非推奨」に設定するか、新しいバージョンをリリースして問題を修正するのが一般的な対応です。

参考資料

• 公式ドキュメント（日本語）
  • GitHub Docs – リリースについて
  • GitHub Docs – GitHub Packagesについて

まとめ：明日から始めるあなたのためのネクストステップ

ReleasesとPackagesを使い分けることで、あなたは自分のソフトウェアを適切な相手に、適切な形で届けることができます。

• ユーザー向けには、Releasesで分かりやすいダウンロードページを。
• 開発者向けには、Packagesで再利用可能な部品を。

そして、これらのプロセスをGitHub Actionsで自動化することで、あなたはヒューマンエラーのない、迅速で信頼性の高いリリースサイクルを実現できるのです。

さあ、次はあなたの番です！

1. まずは簡単なツールを作って、GitHub Releasesで最初のバージョン「v0.1.0」を公開してみましょう。
2. 慣れてきたら、ハンズオンで作成した挨拶ライブラリに新しい機能を追加して、「v1.1.0」としてGitHub Packagesに公開してみましょう。

この記事があなたの開発者ライフの一助となれば幸いです。もし役に立ったと感じたら、ぜひSNSなどでシェアしていただけると嬉しいです！

本記事をご利用いただくにあたって

この記事は、公開時点（2025年9月）の情報に基づき、正確な情報を提供するよう努めています。

しかし、本記事で解説するソフトウェアやサービスの仕様は日々更新されるため、記事内で紹介している画面や手順が、ご覧いただいている時点では変更されている可能性があります。

もし内容に相違がある場合は、各サービスの最新の公式ドキュメントも併せてご参照ください。本記事の情報を利用される際は、ご自身の判断と責任においてお願いいたします。