CI・デプロイで使う

CI は、実行時に aikagi から値を取得します。GitHub Actions は OIDC を使うため、長期間有効な token を置く必要がありません。Cloudflare Workers・Cloudflare Pages には、読み取り専用の実行時キーを 1 つ置きます。Vercel へは、aikagi が値を Vercel の環境変数として同期します。

実行する場所ごとの方法

Cloudflare Workers・Cloudflare Pages のアプリは、起動時に aikagi から値を取得します。そのときに aikagi に接続できないと、アプリの起動（最初のリクエストの処理）は失敗します。値が無いまま動き続けることはありません。Vercel のアプリは、同期された環境変数を読みます。アプリの起動時に aikagi へ接続することはありません。

コマンドの前に付ける

いつも実行しているコマンドの前に aikagi run -- を付けます。値は環境変数として、そのコマンドにだけ渡されます。

aikagi run -- npm test

GitHub Actions

GitHub Actions では、GitHub が job ごとに発行する OIDC（OpenID Connect）の token を使って値を取得します。長期間有効な token を作って GitHub の Secrets に置く方法はありません。

まず、どのリポジトリに値の取得を許可するかを設定します。プロジェクトの左メニューで「環境」を開き、「GitHub Actions」の右上の「＋」（リポジトリを許可）を押して、次の 3 つを指定して保存します。保存すると、workflow に追加する内容がその場で表示されます。

1. リポジトリ（acme/web-app など）。
2. 取得を許可する ref（refs/heads/main や refs/tags/v*）。
3. 読み取りを許可する環境（production など）。

ref は書いたとおりの文字列で照合します。refs/heads/main は main ブランチだけに一致し、main-hotfix には一致しません。末尾に * を付けると、その手前までが同じものすべてに一致します。たとえば refs/tags/v* は、v で始まるすべてのタグに一致します。

次に、workflow の job に次の内容を追加します。

permissions:
  id-token: write
  contents: read
steps:
  - run: |
      curl -fsSL https://aikagi.dev/install.sh | sh
      echo "$HOME/.local/bin" >> "$GITHUB_PATH"
  - run: aikagi run --workspace acme --project web-app --env production -- npm test

permissions: id-token: write が必要です。これが無いと job は OIDC token を受け取れず、値を取得できません。--env を省くと、許可した環境のうち先頭の環境の値を読みます。

OIDC token はその job の中で 1 回だけ使われ、ファイルにも残りません。長期間有効な token が無いため、token の入れ替えや失効し忘れを管理する必要もありません。

Vercel

Vercel では、aikagi が環境の値を Vercel プロジェクトの環境変数へ同期します。ビルド時に読み込まれる値（NEXT_PUBLIC_* など）、ミドルウェア、関数のどこからでも、通常の環境変数として同じ値を読めます。アプリにパッケージを追加する必要はありません。

値を変更する場所は aikagi だけです。Vercel の画面で値を直接変更する必要はありません。

用意するもの

• ワークスペースの管理者の権限。同期を設定できるのは、ワークスペースの管理者だけです。メンバーは、同期の一覧を見ることだけができます。
• Vercel のアクセストークン。Vercel の Account Settings にある Tokens（vercel.com/account/tokens）で作成します。aikagi の画面でアクセストークンを貼り付ける欄にある「Vercel でトークンを作る」からも開けます。作成するときの「Scope」では、同期先のプロジェクトがある team を選びます。作成したアクセストークンは Vercel の画面に 1 回しか表示されないため、その場でコピーしてください。
• 同期先の Vercel プロジェクト。先に Vercel で作成しておきます。

アクセストークンに有効期限を付けた場合は、期限が切れると同期が失敗します。期限が切れる前に、新しいアクセストークンに差し替えてください。

同期を設定する

1. プロジェクトの左メニューで「環境」を開き、「Vercel へ同期」の「＋」（Vercel へ同期を追加）を押します。
2. 「Vercel のアクセストークン」を貼り付けて、「登録」を押します。アクセストークンは暗号化して保存され、保存したあとは画面に表示されません。保存するのはワークスペースごとに 1 回だけです。2 つ目以降のプロジェクトでは、保存済みのアクセストークンを選ぶだけで済みます。
3. 同期先の Vercel プロジェクトを一覧から選びます。プロジェクトが多い場合は、名前で絞り込めます。
4. Production・Preview・Development のそれぞれについて、送る aikagi の環境を選びます。送らない場合は「同期しない」を選びます。最初は、名前が同じ環境が選ばれています。
5. 上書きされる環境変数の名前が表示されるので、内容を確認します。
6. 「同期を始める」を押します。すべての値が Vercel へ送られ、行の「最終同期」に時刻が表示されます。

環境の対応は、たとえば次のようにします。

Vercel の 1 つの環境に送れる aikagi の環境は、1 つだけです。同じ aikagi の環境を、Vercel の複数の環境に送ることはできます。

値を反映する

設定したあとは、値を保存・削除するたびに自動で Vercel へ送られます。キーの名前を変更した場合も、Vercel の環境変数の名前が変わります。

同期した値が使われるのは、次のデプロイからです。これは Vercel の仕様です。動いているデプロイの値は変わりません。すぐに反映したい場合は、Vercel で再デプロイしてください。aikagi が再デプロイを実行することはありません。

値が届いたかどうかは、次の 2 か所で確認できます。

• aikagi の「Vercel へ同期」の行にある「最終同期」の時刻。
• Vercel のプロジェクトの Settings にある Environment Variables の一覧。

環境変数の名前

環境変数の名前は、aikagi run が渡す名前と同じです。フォルダを含むキーの名前の / と - を _ に置き換え、大文字にします。

次のキーは送られません。送られなかったキーは、同期の行に件数が表示され、カーソルを合わせると名前を確認できます。

• 名前が数字で始まるキー（2fa/secret など）。Vercel の環境変数の名前にできません。
• Vercel が予約している名前（TZ、AWS_SECRET_KEY など）になるキー。
• 別のキーと同じ環境変数の名前になるキー（openai/api-key と openai/api_key など）。名前の順で先のキーだけが送られます。

送りたい場合は、aikagi でキーの名前を変更してください。

Vercel にすでに値がある場合

• 同じ名前の環境変数は、aikagi の値で上書きされます。上書きされる名前は、「同期を始める」を押す前に一覧で表示されます。Vercel の値を残したい場合は、先にその値を aikagi に保存してください。
• aikagi に無い名前の環境変数は、そのまま残ります。aikagi が削除するのは、aikagi 自身が Vercel に置いた環境変数だけです。
• 新しく作成される Production と Preview の環境変数は、Vercel の Sensitive な環境変数になります。Sensitive な環境変数の値は、Vercel の画面でも読めなくなります。値は aikagi で確認してください。Development は Vercel が Sensitive に対応していないため、通常の環境変数として作成されます。
• すでにある環境変数は、値だけが置き換わります。種類はほとんどの場合そのままですが、古い形式で暗号化されたものは Sensitive に変わり、暗号化されていないものは暗号化される種類で作り直されます。
• 1 つの環境変数を Vercel の複数の環境で共有していた場合は、同期する環境の分だけが aikagi の値に置き換わります。ほかの環境の値は変わりません。
• Preview の環境変数のうち、特定のブランチだけに設定したものは変更されません。

設定を変える・解除する

同期の行の「…」から操作します。

• 今すぐ同期: すべての値を送り直します。同期に失敗したあとのやり直しにも使えます。
• 設定を変える: 環境の対応を変更できます。「保存して同期」を押すと、新しい設定ですべての値が送り直されます。対応から外した Vercel の環境からは、aikagi が置いた環境変数が削除されます。
• 同期を解除: aikagi が Vercel に置いた環境変数を削除して、同期をやめます。動いているデプロイはそのままで、値が無くなるのは次のデプロイからです。「aikagi で消したキーを Vercel に残す」が有効な場合は、Vercel の環境変数をすべて残したまま同期をやめます。

「設定を変える」の「詳細」を開くと、次の 2 つも変更できます。

• 「同期するフォルダ」: 選んだフォルダの中のキーだけを送ります。最初は「プロジェクト全体」です。
• 「aikagi で消したキーを Vercel に残す」: 有効にすると、aikagi でキーを削除しても Vercel の環境変数は削除されません。

aikagi で環境を削除すると、その環境から送った環境変数は Vercel からも削除されます。プロジェクトを削除した場合も同じです。

アクセストークンを差し替える

「Vercel へ同期」の右上の「…」から「Vercel のトークン」を開きます。「差し替え」を押して新しいアクセストークンを貼り付けると、そのアクセストークンを使っているすべての同期が、新しいアクセストークンで動くようになります。同期を設定し直す必要はありません。

どの同期にも使われていないアクセストークンは、同じ画面で削除できます。

うまくいかないとき

register() で取得していた場合

以前のガイドでは、instrumentation.ts の register() で loadAikagi() を呼ぶ方法を案内していました。この方法は Vercel では動作しません（理由は次の節）。次の順に同期へ切り替えてください。

1. 上の手順で同期を設定し、行の「最終同期」に時刻が表示されることを確認します。
2. instrumentation.ts から loadAikagi() の呼び出しを削除します。ほかで使っていなければ、@aikagi/runtime もアンインストールします。
3. デプロイします。このデプロイから、同期した環境変数が使われます。
4. 「環境」の画面の「実行時の取得元」に Vercel の行が残っている場合は、外します。

Vercel で実行時に取得する場合

Vercel では、アプリの起動時に値を取得する方法は使えません。Vercel が関数に OIDC token を渡すのは、リクエストを処理している間だけです。instrumentation.ts の register() はリクエストより前に実行されるため、OIDC token を受け取れません。

@aikagi/runtime を Vercel で使えるのは、リクエストの処理中に loadAikagi() を呼ぶ場合だけです。この場合は、Vercel のプロジェクトとリンクしたリポジトリ（.vercel/project.json があるディレクトリ）で aikagi init を実行してから、ルートハンドラなどの先頭で呼びます。ビルド時に読み込まれる値には使えません。

// app/api/hello/route.ts
import { loadAikagi } from '@aikagi/runtime'

export async function GET() {
  await loadAikagi()
  return Response.json({ ok: true })
}

Cloudflare Workers・Cloudflare Pages

Cloudflare Workers・Cloudflare Pages では OIDC を使えません。代わりに、production 環境だけを読み取れる実行時キーを 1 つ置きます。

デプロイの設定ファイルがあるリポジトリで aikagi init を実行し、確認されたら Y を押します。実行時キーが作成され、手元でデプロイに使っているログインを使って AIKAGI_KEY として登録されます。登録に失敗した場合は、作成した実行時キーを取り消し、そのことを 1 行で表示します。

// src/index.ts
import { withAikagi } from '@aikagi/runtime'

export default withAikagi({
  async fetch(request, env) {
    // env.OPENAI_API_KEY などが入っています
    return new Response('ok')
  },
})

実行時キーは、プロジェクトの左メニューの「環境」にある「実行時の取得元」で失効できます。aikagi init --force をもう一度実行すると、新しい実行時キーに置き換わります。

CI の中で aikagi init を実行しても、デプロイ先の設定は変わりません。AI ツールに実行させる場合は、--yes を付けると確認なしで最後まで進みます。

デプロイする

Vercel や Cloudflare Workers・Cloudflare Pages へのデプロイも、GitHub Actions の中で同じように実行できます。デプロイに使う token（VERCEL_TOKEN や CLOUDFLARE_API_TOKEN）も aikagi に保存しておけば、GitHub にもデプロイ先にも token を置かずに済みます。

  - run: aikagi run --workspace acme --project web-app --env production -- npx vercel deploy --prod

  - run: aikagi run --workspace acme --project web-app --env production -- npx wrangler deploy

監査ログ

値を取得するたびに、監査ログに記録されます。取得した主体は次のように表示されます。

• GitHub Actions: github:acme/web-app#<run_id>（リポジトリと実行番号）
• Vercel（実行時に取得した場合）: vercel:acme/web-app@production（team・プロジェクト・Vercel の環境）
• Cloudflare Workers・Cloudflare Pages: key:<実行時キーの名前>

Vercel への同期は、値を変更した人の操作として記録されます。同期 1 回につき 1 行で、記録されるのは送った件数とキーの名前だけです。値そのものは記録されません。