パッケージ管理とは|Azure Artifacts と GitHub Packages にパイプラインから発行して権限と不変性を実機確認(DevOps 編 10)

DevOps

はじめに

DevOps 編の 10 回目は、パッケージ管理。
自分たちで作ったライブラリや、npmjs などから取り込む依存関係を、どこに置いてどう配るかを扱う。
Azure DevOps では Azure Artifacts、GitHub では GitHub Packages がこの役割を持つ。
実機では、同じような npm パッケージを両方にパイプラインから発行し、権限が足りないと発行できないこと、同じ版は二度と発行できないことを確かめる。

前回:エージェント基盤

エージェント基盤とは|セルフホステッド エージェントと Managed DevOps Pools を同じパイプラインで実機比較(DevOps 編 9)
Azure Pipelines のエージェントを 4 種類で比較し、セルフホステッド エージェントと Managed DevOps Pools で同じパイプラインを動かして、登録・待ち・VM の用意の違いを実機で確認。

パッケージ管理の考え方

パッケージ管理では、パッケージを「フィード」(GitHub では「レジストリ」)にまとめる。
作る側はビルドとテストのあとにパッケージを発行し、使う側はフィードから取り込む。

パッケージ管理の流れ

パッケージの版は、多くのチームがセマンティック バージョニング(SemVer)で付ける。
1.2.3 なら、1 がメジャー(互換性のない変更)、2 がマイナー(機能の追加)、3 がパッチ(不具合の修正)。

Azure Artifacts のパッケージは不変で、発行した版の中身は変えられない。
あとで削除しても版の番号は予約されたままで、同じ番号は二度と使えない。
同じ版で中身が違うものを受け取る事故を防ぐための仕組み。

npmjs.com や NuGet.org などのパブリック レジストリは、アップストリーム ソースとしてフィードにつなげる。
フィードに無いパッケージはアップストリームから取り込まれ、そのコピーがフィードに保存される。
設定ファイルにはフィードを 1 つだけ書けばよく、取り込み先の順番が決まるので、ビルドの結果が毎回同じになる。
パブリック レジストリが一時的に止まっても、保存したコピーで開発を続けられる。

公式ドキュメント:
アップストリーム ソースとは | Microsoft Learn
フィード ビューとは | Microsoft Learn
パッケージの削除と回復 | Microsoft Learn

Azure Artifacts の仕様

Azure Artifacts のフィードには、npm、NuGet、Maven、Python、Cargo、ユニバーサル パッケージを入れられる。
1 つのフィードに複数の種類を混ぜてもよい。

Azure Artifacts のフィード

スコープ

フィードはプロジェクト スコープか組織スコープで作る。
新しく作るならプロジェクト スコープが推奨されている。
組織スコープのフィードは、あとからプロジェクト スコープに変えられない。

別のプロジェクトのパイプラインからプロジェクト スコープのフィードを使うときは、プロジェクト コレクション ビルド サービスと、実行するプロジェクトのビルド サービスの両方にロールが必要になる。

パブリック プロジェクトのプロジェクト スコープのフィードは、パブリック フィードとして誰でも使える。
ただし Azure DevOps のパブリック プロジェクトは廃止が決まっていて、2027 年から既存のパブリック プロジェクトはプライベートに変換され、パブリック フィードも公開されなくなる。

公式ドキュメント:
Azure Artifacts フィードとは | Microsoft Learn
フィード スコープ: プロジェクトフィードと組織フィード | Microsoft Learn

アップストリーム ソース

アップストリーム ソースには、パブリック レジストリ(npmjs、NuGet Gallery、PyPI、Maven Central など)、同じ組織のフィード、同じ Microsoft Entra テナントの別の組織のフィードを選べる。
パッケージの種類ごとに、1 つのフィードに 20 個まで設定できる。

パッケージの検索は、フィードに直接発行したもの、アップストリームから保存したもの、アップストリームにあるもの(設定の順)の順に行われる。
アップストリームから保存するには、Feed and Upstream Reader(Collaborator)以上のロールが要る。

アップストリームが有効なフィードでは、アップストリームにすでにある版と同じ版を発行できない。
たとえば npmjs にある名前と版をそのままフィードに発行することはできない。

公式ドキュメント:
アップストリーム ソースとは | Microsoft Learn
アップストリーム ソースのセットアップ | Microsoft Learn

ビューと昇格

フィードには、@Local、@Prerelease、@Release の 3 つのビューが最初からある。
発行できるのは @Local(既定のビュー)だけで、検証したパッケージを @Prerelease や @Release に昇格して共有する。
@Prerelease と @Release は名前の変更や削除ができる。

昇格には Feed Publisher(Contributor)以上が必要。
昇格したパッケージを前のビューに戻すこと(降格)はできない。

ビューにアクセスできる人は、フィードそのものに直接アクセスできなくても、そのビューからパッケージをダウンロードできる。
パッケージへのアクセスを完全に絞るなら、フィードとビューの両方を絞る。

公式ドキュメント:
フィード ビューとは | Microsoft Learn
パッケージの昇格とフィード ビューの管理 | Microsoft Learn

ロール

フィードの権限は、4 つのロールで決まる。

フィードのロール

パイプラインの ID(プロジェクトのビルド サービス、プロジェクト コレクション ビルド サービス)には、既定で Feed and Upstream Reader(Collaborator)が付く。
依存関係の取り込みはできるが、そのままではパッケージを発行できない。
パイプラインから発行するには、パイプラインの ID を Feed Publisher(Contributor)にする。

公式ドキュメント:
アクセス許可の管理 | Microsoft Learn
Azure Pipelines で npm パッケージを発行する (YAML/クラシック) | Microsoft Learn

保持と削除

アイテム保持ポリシーを有効にすると、「パッケージごとのバージョンの最大数」と「最近ダウンロードしたパッケージを保持する日数」の両方に当てはまる古い版が、1 日 1 回自動で削除される。
ビューに昇格した版は、アイテム保持ポリシーでは削除されない。

削除した版はごみ箱に移り、30 日たつと完全に削除される。
その間は Feed Owner が復元できる。
npm の場合、版を残したまま利用者に警告を出すなら「非推奨」(npm deprecate)を使う。

公式ドキュメント:パッケージの削除と回復 | Microsoft Learn

料金と上限

Azure Artifacts のストレージは、組織ごとに 2 GiB まで無料。
2 GiB に達すると新しいパッケージを発行できなくなるので、古いパッケージを削除するか、組織の課金を設定して使った分を支払う。

項目上限
バージョン数パッケージ ID ごとに 5,000
パッケージ ID の数フィードごとに無制限
アップストリームパッケージの種類ごと、フィードごとに 20
npm のサイズファイルごとに 500 MiB(package.json は 375 KB まで)
ユニバーサル パッケージのサイズファイルごとに 4 TiB

公式ドキュメント:
Azure Artifacts とは | Microsoft Learn
パッケージのサイズと数の制限 | Microsoft Learn

GitHub Packages の仕様

GitHub Packages は、GitHub でパッケージをホストするサービス。
npm、RubyGems、Apache Maven、Gradle、NuGet のレジストリと、コンテナー用の Container registry がある。

GitHub Packages の仕組み

アクセス許可のモデル

Container registry、npm、NuGet、RubyGems は、ユーザーや Organization 単位で細かいアクセス許可を設定できる。
パッケージをリポジトリにリンクすると、既定ではリポジトリのアクセス許可を継承する。
Apache Maven と Gradle は、リポジトリのアクセス許可と可視性をそのまま使う。

npm レジストリで扱えるのはスコープ付きのパッケージ(@NAMESPACE/PACKAGE-NAME)だけで、名前とスコープは小文字にする。
レジストリの URL は https://npm.pkg.github.com。

公式ドキュメント:
GitHub Packagesの権限について – GitHub Docs
npmレジストリの利用 – GitHub Docs

認証

ワークフローの中では GITHUB_TOKEN を使うことが推奨されている。
ワークフローのリポジトリに関連するパッケージを、発行・インストール・削除・復元できる。
発行するには、ワークフローの permissions で packages: write を付ける。

ワークフローの外(手元の PC など)では、personal access token (classic) だけが使える。
スコープは read:packages(ダウンロード)、write:packages(発行)、delete:packages(削除)。

GITHUB_TOKEN でワークフローから作ったパッケージは、既定で次のようになる。
・ワークフローを動かしたリポジトリの可視性とアクセス許可を継承する
・そのリポジトリの管理者が、パッケージの管理者になる
・発行したリポジトリには、パッケージへの Admin が付く

公式ドキュメント:
GitHub Actionsでのパッケージの公開とインストール – GitHub Docs
パッケージのアクセス制御と可視性の設定 – GitHub Docs

料金と削除

パブリック パッケージは無料。
プライベート パッケージは、プランごとのストレージと転送量の無料枠を超えると課金される(GitHub Free はストレージ 500MB、転送 月 1GB)。
このストレージは、Actions の成果物と合算される。
ワークフローから GITHUB_TOKEN でダウンロードした分は、転送量に数えない。

削除したパッケージは、30 日以内なら復元できる。
ダウンロード数が 5,000 を超えた版があるパブリック パッケージは削除できない。

公式ドキュメント:
GitHub Packages の概要 – GitHub Docs
GitHub パッケージの課金 – GitHub Docs
パッケージを削除および復元する – GitHub Docs

Azure Artifacts と GitHub Packages の比較

項目Azure ArtifactsGitHub Packages
パッケージの種類npm、NuGet、Maven、Gradle、Python、Cargo、ユニバーサル パッケージnpm、RubyGems、Maven、Gradle、NuGet、コンテナー イメージ
まとまりの単位フィード(プロジェクト / 組織スコープ)ユーザー / Organization(リポジトリにリンク)
パブリック レジストリの利用アップストリーム ソースで取り込み、フィードに保存npm では、すべての要求を GitHub Packages 経由にすると npmjs.org のパッケージも使える
リリースの段階分けビュー(@Local → @Prerelease → @Release)版と npm のタグ(latest など)で管理
パイプラインからの認証npmAuthenticate@0 など。ビルド サービスのロールで制御GITHUB_TOKEN と permissions: packages: write
無料の範囲組織ごとに 2 GiBパブリックは無料。プライベートはプランの無料枠まで
観点メリットデメリット
Azure Artifactsアップストリームで外部の依存関係もまとめて保存できる。
ビューで検証済みの版だけを配れる
2 GiB を超えると課金の設定が必要。
パブリック フィードは 2027 年から公開されなくなる
GitHub Packagesソース コード、Actions、パッケージを GitHub だけで完結できる。
パブリックなら無料
プライベート パッケージは、プランの無料枠(GitHub Free は 500MB)を超えると課金される。
このストレージは Actions の成果物と合算

構築手順

今回の構成と実施すること

今回の構成
手順実施すること確かめること
①フィード blog-feed を作り、npmjs をアップストリームにするアップストリームとビューの設定
②パイプラインから npm パッケージを発行するビルド サービスが Collaborator のままでは 403。
依存関係はフィードに保存される
③ビルド サービスを Feed Publisher にする発行が成功する
④同じ版、削除した版をもう一度発行するどちらも発行できない
⑤1.0.0 を @Release に昇格するビューの表示が変わる
⑥GitHub Actions から GitHub Packages に発行するpackages: write の有無で成否が分かれる。
可視性はリポジトリから継承される

① フィードを作り、npmjs をアップストリームにする

「Artifacts」⇒「Create Feed」でフィードを作る。

フィードの作成
番号項目説明
1Nameフィード名。URL に入る
2Visibilityパッケージを見られる人。
今回は組織のメンバー(Members of blog-devops-1114)
3ScopeProject(推奨)か Organization

作成画面には、ドキュメントにある「アップストリーム ソース」のチェックがなかった。
作成直後のフィード設定の「Upstream Sources」は空だった。

作成直後のアップストリーム
番号項目説明
1Upstreams for blog-feedアップストリームが 1 つもない

「Add Upstream」で「Public source」を選ぶ。

アップストリームの種類
番号項目説明
1Public sourceNuGet.org や npmjs.com などのパブリック レジストリ。
ほかに、同じ組織のフィード、別の組織のフィードを選べる
npmjs を選ぶ
番号項目説明
1Public source一覧から npmjs(https://registry.npmjs.org/)を選ぶ
追加したアップストリーム
番号項目説明
1npmjs種類は Public。
複数あるときは Move Up / Move Down で順番を決める
2Save保存して確定する

「Permissions」タブを見ると、パイプラインの ID(boards-demo Build Service)は Feed and Upstream Reader(Collaborator)だった。

フィードの権限
番号項目説明
1boards-demo Build Serviceプロジェクトのビルド サービス。
既定のロールは Feed and Upstream Reader(Collaborator)
フィードのビュー
番号項目説明
1Local / Prerelease / Release最初からある 3 つのビュー。既定のビューは Local

公式ドキュメント:
Azure Artifacts フィードとは | Microsoft Learn
アップストリーム ソースのセットアップ | Microsoft Learn

② パイプラインから発行する(権限が足りない)

cicd-demo リポジトリに pkg フォルダーを作り、パッケージ blog-d10-hello を置いた。
依存関係に npmjs の is-number を入れている。

{
  "name": "blog-d10-hello",
  "version": "1.0.0",
  "description": "Sample package for Azure Artifacts",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "is-number": "^7.0.0"
  }
}

package.json と同じフォルダーの .npmrc に、フィードの URL を書く(資格情報は書かない)。

registry=https://pkgs.dev.azure.com/<組織>/boards-demo/_packaging/blog-feed/npm/registry/

パイプラインでは、npmAuthenticate@0 で .npmrc にビルドの資格情報を足してから、npm install と npm publish を動かす。

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
- task: npmAuthenticate@0
  displayName: Authenticate to blog-feed
  inputs:
    workingFile: pkg/.npmrc

- script: npm install
  displayName: npm install (via upstream)
  workingDirectory: pkg

- script: npm publish
  displayName: npm publish
  workingDirectory: pkg

1 回目の実行では、npm install は成功し、npm publish が 403 で失敗した。

発行の 403
番号項目説明
1403 ForbiddenUser '***' lacks permission to complete this action. You need to have 'AddPackage'.
ビルド サービスに発行の権限がない

フィードには、npm install で取り込んだ is-number 7.0.0 が保存されていた。
Source は npmjs で、Collaborator のロールでもアップストリームからの保存はできた。

アップストリームから保存されたパッケージ
番号項目説明
1is-numberSource が npmjs。アップストリームから保存されたコピー

公式ドキュメント:
Azure Pipelines で npm パッケージを発行する (YAML/クラシック) | Microsoft Learn
npmAuthenticate@0 – npm authenticate (タスクランナー用) v0 タスク | Microsoft Learn
Azure Artifacts フィードに接続する – npm | Microsoft Learn

③ ビルド サービスを Feed Publisher にする

フィード設定の「Permissions」で boards-demo Build Service を選び、「Edit」でロールを変える。

ロールの変更
番号項目説明
1Feed Publisher (Contributor)パッケージの発行、昇格、非推奨にする操作ができる
変更後の権限
番号項目説明
1boards-demo Build ServiceFeed Publisher (Contributor) になった

もう一度動かすと、発行が成功した。

発行の成功
番号項目説明
1npm publishPublishing to https://pkgs.dev.azure.com/…/blog-feed/npm/registry/ のあと + blog-d10-hello@1.0.0
2npm publishステップが成功
フィードのパッケージ
番号項目説明
1blog-d10-helloSource が This feed。直接発行したパッケージ

パッケージの画面の「Provenance」には、発行したパイプライン、実行番号、コミットが出る。

パッケージの詳細
番号項目説明
1Provenance発行したパイプライン pkg-publish、実行 20261115.2、コミットとリポジトリ
2Viewsいまは Local だけ
3Promoteビューに昇格する

④ 同じ版、削除した版は発行できない

version を変えずにもう一度動かすと、npm publish が失敗した。

同じ版の発行
番号項目説明
1エラーYou cannot publish over the previously published versions: 1.0.0.

次に version を 1.0.1 にして発行し、1.0.1 をフィードから削除した(ごみ箱に移る)。

パッケージの削除
番号項目説明
1Delete packages?選んだ版をフィードのごみ箱に送る。
その版に頼っているプロジェクトはビルドできなくなるという警告が出る
ごみ箱
番号項目説明
1blog-d10-hello 1.0.1削除した日と、完全に削除される予定日が出る

package.json の version は 1.0.1 のまま、もう一度発行した。
削除した版でも、同じ番号では発行できなかった。

削除した版の発行
番号項目説明
1403 ForbiddenThe version 1.0.1 of blog-d10-hello has been deleted. It cannot be restored or pushed.

公式ドキュメント:パッケージの削除と回復 | Microsoft Learn

⑤ @Release に昇格する

パッケージの画面で「Promote」を選び、昇格先のビューを選ぶ。

昇格
番号項目説明
1blog-d10-hello 1.0.0昇格する版
2Select a viewblog-feed@Prerelease か blog-feed@Release。
今回は Release
昇格後の版
番号項目説明
11.0.0Views に Release と Local。
1.0.1(削除する前)は Local だけだった

フィード設定の「Feed Details」には、アイテム保持ポリシーの設定がある(今回は有効にしていない)。

アイテム保持ポリシー
番号項目説明
1Retention policiesMaximum number of versions per package と Days to keep recently downloaded packages。
ビューに昇格した版は削除されない

公式ドキュメント:
パッケージの昇格とフィード ビューの管理 | Microsoft Learn
パッケージの削除と回復 | Microsoft Learn

⑥ GitHub Actions から GitHub Packages に発行する

パブリック リポジトリ pkg-demo を作り、スコープ付きの名前でパッケージを置いた。
repository にリポジトリの URL を書くと、発行したパッケージがリポジトリにリンクされる。

{
  "name": "@<OWNER>/hello-lib",
  "version": "1.0.0",
  "description": "Sample package for GitHub Packages",
  "main": "index.js",
  "files": ["index.js"],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/<OWNER>/pkg-demo.git"
  }
}

ワークフローでは、setup-node の registry-url に GitHub Packages を指定し、NODE_AUTH_TOKEN に GITHUB_TOKEN を渡す。
最初は permissions を contents: read だけにした。

name: publish

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 22
          registry-url: https://npm.pkg.github.com
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

実行すると、npm publish が 403 で失敗した。

GitHub Packages の 403
番号項目説明
1403 ForbiddenPermission installation not allowed to Create organization package
GITHUB_TOKEN に packages の書き込み権限がない

permissions に packages: write を足して、もう一度動かした。

permissions:
  contents: read
  packages: write
GitHub Packages への発行の成功
番号項目説明
1StatusSuccess。9 秒で終わった

リポジトリの「Packages」に hello-lib 1.0.0 ができた。

GitHub のパッケージ
番号項目説明
1hello-lib 1.0.0package.json の description が出る。
インストールのコマンドも表示される
2Details所有者と、リンクされたリポジトリ pkg-demo

パッケージの「Package settings」では、リンク先のリポジトリと、Actions からのアクセスを確認できる。

パッケージの設定
番号項目説明
1Repository sourcepackage.json の repository で指定したリポジトリ
2Manage Actions access発行した pkg-demo に Role: Admin が付いていた
アクセスの継承と可視性
番号項目説明
1Inherited accessInherit access from source repository がオン。
リポジトリのアクセス許可を継承する
2Change package visibilityThis package is currently public. パブリック リポジトリから発行したので、パッケージもパブリックになった

公式ドキュメント:
GitHub Actionsでのパッケージの公開とインストール – GitHub Docs
npmレジストリの利用 – GitHub Docs
パッケージのアクセス制御と可視性の設定 – GitHub Docs

実機でつまずいた点

refusing to allow an OAuth App to create or update workflow without workflow scope

GitHub CLI(gh auth login)で作ったトークンで、ワークフローのファイルを含むコミットを push すると拒否された。
このトークンのスコープは repo などで、workflow スコープが入っていなかった。
.github/workflows の中のファイルを作ったり変えたりするには、workflow スコープが要る。
今回はワークフロー以外のファイルだけ push し、publish.yml は GitHub の画面で作成・編集した。

ワークフローのファイルを push できない

発展

項目内容
ユニバーサル パッケージNuGet や npm などの形式に当てはまらないファイルも、名前と版を付けて Azure Artifacts に保管できる(最大 4 TiB)。
Azure CLI の Azure DevOps 拡張機能で発行する。
パブリック フィードでも匿名ではダウンロードできない
ほかの種類NuGet、Maven、Python も、フィードに接続してアップストリームとビューを同じように使える
Container registryGitHub のコンテナー用レジストリ(ghcr.io)。
パブリックのイメージは認証なしで pull できる。
ストレージと帯域幅は現在無料
組織をまたぐ共有同じ Microsoft Entra テナントの別の組織のフィードを、アップストリームとして追加できる

公式ドキュメント:
Azure Artifacts フィードからユニバーサル パッケージを発行する | Microsoft Learn
GitHub Packages の概要 – GitHub Docs

推奨構成

項目推奨
フィードのスコーププロジェクト スコープで作る
取り込み先.npmrc や nuget.config にはフィードを 1 つだけ書き、パブリック レジストリはアップストリームでつなぐ
リリース@Local に発行して検証し、配ってよい版を @Prerelease / @Release に昇格する
パイプラインの権限発行するパイプラインのビルド サービスだけを Feed Publisher にする。
ほかは既定の Collaborator のまま
項目推奨
保持古い版がたまる前にアイテム保持ポリシーを有効にする。
残したい版はビューに昇格する
GitHub ActionsGITHUB_TOKEN を使い、発行するジョブにだけ packages: write を付ける
版の付け方SemVer で付け、同じ版を出し直さない(直すときは版を上げる)
アクションの指定actions/checkout などはコミット SHA で固定する

公式ドキュメント:Azure Artifacts のベスト プラクティス | Microsoft Learn

注意事項

項目内容
パッケージは不変発行した版は変えられない。削除しても同じ版の番号では発行できない
既定の権限ビルド サービスは既定で Collaborator なので、そのままでは発行できない(403)
アップストリームと同じ版アップストリームが有効なフィードには、アップストリームにある版と同じ版を発行できない
昇格昇格した版は前のビューに戻せない
項目内容
無料枠Azure Artifacts は組織ごとに 2 GiB。
超えると発行できなくなる
パブリック フィード2027 年から、パブリック プロジェクトはプライベートに変換され、パブリック フィードも公開されなくなる
GitHub Packages の可視性ワークフローで作ったパッケージは、リポジトリの可視性を継承する。
パブリック リポジトリからはパブリックになる
workflow スコープワークフローのファイルを push するトークンには workflow スコープが要る

公式ドキュメント:
Azure Artifacts フィードとは | Microsoft Learn
パッケージのサイズと数の制限 | Microsoft Learn
GitHub Actionsでのパッケージの公開とインストール – GitHub Docs

まとめ

・パッケージはフィード(レジストリ)にまとめ、パブリック レジストリはアップストリームでつなぐ。
・Azure Artifacts のフィードには、スコープ、アップストリーム、ビュー、4 つのロールがある。
・パイプラインのビルド サービスは既定で Collaborator で、依存関係は保存できたが、発行は 403 になった。
Feed Publisher にすると発行できた。
・同じ版も、削除した版も、もう一度は発行できなかった。
・GitHub Packages では、GITHUB_TOKEN に packages: write を付けると発行でき、パッケージはリポジトリの可視性を継承した。

次回:テスト

テストとは|Azure Load Testing の仕組みと Azure Test Plans の手動テストを実機で通す(DevOps 編 11)
テストを自動・負荷・手動に分けて整理。Azure Load Testing の仕組みと不合格の条件・料金、Azure Test Plans の計画・スイート・ケースとアクセス レベルを解説し、手動テストからバグ起票まで実機で確かめた。

コメント

タイトルとURLをコピーしました