サーバーレスに新規secretを足さず、ローカルCLI+定期タスクで外部API連携を補完する

状況

Next.js等のサーバーレスアプリ(Vercel等)から外部API(GitHub Issue作成など)を呼びたいが、 そのAPIを叩くための認証情報(personal access token等)を新規にホスティング環境のenv/secretへ 追加したくない場面がある。理由は様々: 新規token発行の手間、secret管理を増やしたくない、 すでに開発機に認証済みの公式CLI(gh, aws, stripe等)があるので二重に鍵を持ちたくない、等。

解決パターン: ローカル定期同期スクリプト

1. サーバー側は「ベストエフォート」に留める: サーバーのAPI route等に外部API呼び出しコードは 書いてよいが、対応するtoken系env varが未設定でも動作は失敗させず、単に「今回はスキップ」として 本来のリクエスト(DB保存等)は成功させる。未処理の項目は「未処理フラグ」(例: external_ref_url is null) で判別できるようにDBに残す。
2. ローカル同期スクリプトが差分を拾う: 開発機で既に認証済みのCLI(gh, aws, 等)を使い、 「未処理フラグが立っている行」をDBから取得 → 外部APIへ登録 → 結果(URL/ID)をDBへ書き戻す。 同じ行を二重処理しないよう、書き戻し済みの行は次回スキップする(冪等)。
3. OSの定期タスクで自動実行: Windows Task Scheduler(schtasks/Register-ScheduledTask)や cron/launchdで、このスクリプトを一定間隔(例: 30分毎)で実行する。ラッパー(.ps1/.sh)が 本体スクリプトの標準出力をログファイルへ追記する形にしておくと、後からtailするだけで 稼働確認ができる。
4. 本番データを汚さずにE2E検証する: ローカルCLI経由で実際に外部APIへ書き込みが起きるため、 検証時は「使い捨てレコードを1件作る→スクリプト実行→期待通り外部リソースが作られてDBに 書き戻ることを確認→作った外部リソースをclose/削除→使い捨てレコードもDELETE」という throwaway方式を使う。共有状態(既存の実データ)を書き換えるE2Eは書かない。

PowerShellラッパーの落とし穴(Windows特有)

• 日本語を含むパス(リポジトリのフォルダ名等)がある環境で、BOM無し.ps1をPowerShell 5.1が 実行すると文字化けやパーサーエラー(TerminatorExpectedAtEndOfString)を起こすことがある。 $PSScriptRootはASCIIセーフなので、リポジトリルートをハードコードせず Split-Path -Parent $PSScriptRootから導出する。
• 子プロセス(node等)のUTF-8出力をそのままOut-Fileすると文字化けする。 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8を先頭で設定する。

汎用化のポイント

• この構成は「サーバーレス環境に新しいsecretを増やしたくない」× 「開発機に既に認証済みCLIがある」 という条件がそろうあらゆる外部API連携に適用できる(GitHub Issue化に限らず、Slack投稿、 クラウドストレージへのバックアップ、監視ツールへのアラート転送等)。
• 「サーバー側はベストエフォート＋未処理フラグ／ローカル側は冪等な差分同期＋定期タスク」という 役割分担を先に決めてから実装すると、どちらか一方が落ちても機能全体が止まらない。