# Takumi Guard の npm・PyPI 向け GitHub Actions を更新

Takumi Guard の GitHub Actions [flatt-security/setup-takumi-guard-npm](https://github.com/flatt-security/setup-takumi-guard-npm) と [flatt-security/setup-takumi-guard-pypi](https://github.com/flatt-security/setup-takumi-guard-pypi) を更新しました。

これらの変更は、すでに npm 向けの [v1.4.0](https://github.com/flatt-security/setup-takumi-guard-npm/releases/tag/v1.4.0)、PyPI 向けの [v1.3.0](https://github.com/flatt-security/setup-takumi-guard-pypi/releases/tag/v1.3.0) として提供していますが、<strong><u>2026 年 10 月 13 日（火）</u></strong>に `v1` タグをそれぞれのバージョンに更新する予定です。

本記事では、変更内容と、必要に応じてご確認・ご対応いただきたい事項についてご案内します。

## 影響を受けるワークフロー {#scope}

対象となる Action は次の 2 つです。

- [flatt-security/setup-takumi-guard-npm](https://github.com/flatt-security/setup-takumi-guard-npm)
- [flatt-security/setup-takumi-guard-pypi](https://github.com/flatt-security/setup-takumi-guard-pypi)

影響を受けるのは、Action を **`@v1` タグで参照しているワークフロー**です。

コミット SHA やバージョン番号（`@v1.2.0` など）でバージョンを固定しているワークフローは、今回の変更による影響を受けません。ただし、以前のバージョンでは、Takumi Guard を経由せずに install が行われたり、bot に紐づかない匿名の install として扱われたりする場合があるため、固定しているバージョンを最新のリリースに更新することをおすすめします。

## npm 向けの Action（v1.4.0） {#npm}

これまでの npm 向けの Action では、レジストリとトークンの設定を、チェックアウトしたリポジトリの直下にある `.npmrc` に書き込んでいました。しかし、サブディレクトリや `working-directory` を指定してインストールする場合、この設定が読み込まれず、Takumi Guard を経由せずにパッケージを取得する可能性がありました。

修正版では、設定をチェックアウトしたリポジトリの外にあるジョブ専用の `.npmrc` に書き込み、環境変数を通じてその場所をジョブ内の後続のステップに引き継ぐようにしました。これにより、どのディレクトリでインストールを実行する場合でも Takumi Guard を経由するようになり、チェックアウトしたリポジトリのファイルも変更されなくなります。

この変更に伴い、npm・pnpm・Yarn Classic をご利用の場合、以下のようなワークフローでは修正が必要となることがあります。

- Dockerfile で `COPY .npmrc` を使用しているワークフロー
  - `docker build --secret id=npmrc,src="$NPM_CONFIG_USERCONFIG"` のようにビルドシークレットとして `.npmrc` を渡し、Dockerfile では `RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci` のように使用してください。
- リポジトリの `.npmrc` に `//npm.flatt.tech/:_authToken=` の行があるワークフロー
  - リポジトリの `.npmrc` に設定されたトークンが Bot のトークンより優先されるため、その行を削除してください。

詳細については、[v1.3.0](https://github.com/flatt-security/setup-takumi-guard-npm/releases/tag/v1.3.0) および [v1.4.0](https://github.com/flatt-security/setup-takumi-guard-npm/releases/tag/v1.4.0) のリリースノートでもご案内していますので、あわせてご確認ください。

## PyPI 向けの Action（v1.3.0） {#pypi}

これまでの PyPI 向けの Action では、トークンを環境変数 `PIP_INDEX_URL` と `UV_INDEX_URL` にのみ設定していました。しかし、Poetry はこれらの環境変数を参照しないため、`bot-id` を指定していても、Poetry によるパッケージのインストールは Bot に紐づいていませんでした。

また、`set-index-url: false` を指定した場合でも、認証に成功すると Action がこれらの環境変数を Takumi Guard の URL で上書きしていたため、利用者自身が設定したインデックスよりも Action の設定が優先されていました。

修正版では、トークンをジョブ専用の `.netrc` に書き込み、環境変数 `NETRC` を通じて、その場所をジョブ内の後続のステップに引き継ぐようにしました。あわせて、プロジェクトの設定で Takumi Guard を指している uv のインデックスにもトークンを渡します。

この変更に伴い、以下のようなワークフローでは修正が必要となる場合があります。

- pip・uv を利用しており、`set-index-url: false` を指定して Action によるインデックスの設定に依存しているワークフロー
  - インデックスに `https://pypi.flatt.tech/simple/` を指定してください。
- uv を利用しており、Action を `actions/checkout` より前に実行しているワークフロー
  - Action を `actions/checkout` の後に実行してください。

詳細については、[v1.2.0](https://github.com/flatt-security/setup-takumi-guard-pypi/releases/tag/v1.2.0) および [v1.3.0](https://github.com/flatt-security/setup-takumi-guard-pypi/releases/tag/v1.3.0) のリリースノートでもご案内していますので、あわせてご確認ください。

## npm・PyPI 向けの Action に共通する変更 {#common}

`bot-id` を指定していて **Bot の認証に失敗した場合、ステップが失敗**するようになります。

現在は、`set-registry`・`set-index-url` が既定値の場合、認証に失敗するとエラーの注記を表示したうえで匿名モードのまま処理を続けるため、ジョブ自体は成功します。しかし、インストールは Bot に紐づかず、ダウンロード追跡や[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications)の対象にもなりません。

RubyGems・Go・Packagist 向けの Action では、すでに認証に失敗した時点でステップが失敗するようになっており、今回の更新で npm・PyPI 向けの Action も同じ挙動になります。なお、`bot-id` を省略した匿名モードの挙動は変わりません。

現在のワークフローで認証に失敗している場合、ジョブは匿名モードのまま成功しますが、実行結果の Annotations にエラーが表示されています。10 月 13 日以降はステップ自体が失敗するようになるため、エラーの内容をご確認のうえ、必要な修正をお願いいたします。