geekfujiwara/codeappsdevelopmentstandard/alm

ALM（秘匿化・汎用化・CI/CD）共通スキル

コードファースト資産を安全に Git へ載せ、機械判定だけでデプロイまで到達させるための共通基盤。 プロダクト非依存であり、foundry-autopilot（Foundry エージェント）、code-apps（Code Apps）など どのスキルからも同じ仕組みで利用できる。デプロイの実処理だけを各プロダクトスキルへ委譲する。

前提ツール: Python 3.10+、Git、Azure CLI（az）。

シークレットストアに応じて GitHub CLI（gh）または az extension add --name azure-devops を追加する。

事前確認（会話の最初に 1 回だけ）

本スキルの利用が確定したら、standard の共通契約に加え、 1 回の AskUserQuestion で次をまとめて確認する。

personal access token や長期 client secret を既定にせず、OIDC / workload identity を優先する。 repository 管理権限、secret backend、CI identity のいずれかが未確定ならパイプラインを有効化しない。

各プロダクトスキルとの責務分担

プロダクトスキル側は「何をデプロイするか」だけを定義し、 「どう秘匿化し、どう検証し、どう承認して記録するか」は本スキルに従う。

スキル同梱スクリプト

テーマリポジトリの scripts/ へそのままコピーして使う（alm_config.py を必ず一緒に置く）。

Step 1: レイアウトを alm.config.json で宣言する

スクリプトは無改変で使い、リポジトリごとの差分は設定ファイルだけにする。 未作成なら既定値（**/*.template.* をテンプレート、.env を追跡禁止）で動く。

Copy-Item .github/skills/alm/scripts/*.py scripts/
Copy-Item .github/skills/alm/alm.config.example.json alm.config.json

Step 2: 秘匿値を .env に隔離する

1. .env（実値・.gitignore）と .env.example（プレースホルダーのみ・コミット対象）を作る。

雛形は references/.env.example。

1. テンプレートには実値を一切書かない。環境依存値はすべて ${VAR} にする。
2. 公開識別子（アプリ名・エージェント名など）は non_secret_vars に入れる。

これを入れないと、文章中の名称まで ${VAR} に置換されてテンプレートが壊れる。

python scripts/render.py --template agents/<name>/agent.template.yaml --output agents/<name>/agent.yaml

Step 3: pre-commit ゲートを有効化する

git config core.hooksPath .githooks

#!/bin/sh
set -e
# 1. 実値入りファイルを汎用化し、シークレットストアへ同期してテンプレートをステージ
python scripts/sanitize.py --env .env --set-secrets --stage
# 2. ステージ済み差分に実値が残っていないか検査（残っていればコミット中止）
python scripts/check_secrets.py --env .env

.gitignore を含む雛形一式は references/repo-scaffold.md。

Step 4: シークレットストアを選ぶ

SECRET_BACKEND で送信先が切り替わる。Git ホスティングとは独立に選べる。

python scripts/sanitize.py --env .env --set-secrets --secret-backend github --stage
python scripts/sanitize.py --env .env --set-secrets --secret-backend azure-devops --stage
python scripts/sanitize.py --env .env --set-secrets --secret-backend keyvault --stage

Azure へのログインは必ず OIDC / ワークロード ID フェデレーションを使い、 クライアントシークレットを保管しない。設定手順は references/ci-providers.md。

Step 5: レビューゲートを CI に組み込む

5.1 最小構成（決定論ゲートのみ）

PR で review_sanitization.py を実行し、必須ステータスチェックにする。 これだけで「実値混入」「テンプレート未汎用化」はマージできなくなる。

5.2 推奨構成（自律レビューゲート連鎖）

5 体のレビューエージェントを直列に並べ、全ゲート PASS のときだけデプロイする。 各エージェントは gate_rules.py のルールを評価するだけなので、判定は決定論的で人手承認が不要。

python scripts/gate_rules.py --gate quality --out .gate/quality.json
python scripts/gate_rules.py --gate release --verdict-dir .gate
python scripts/review_report.py --verdict-dir .gate --out .gate/review-report.md

ワークフロー定義・ルール一覧・プロンプトの書き方は references/review-gates.md。

Step 6: デプロイを承認付きで実行する

1. 既定ブランチへのマージでデプロイジョブを起動する。
2. デプロイの実処理はプロダクトスキルが定義する（foundry-autopilot なら deploy.py、

code-apps なら npm run deploy）。ALM 側は認証・環境・順序だけを規定する。

1. 承認の扱いは 2 択にする。両方を併用しない。

• 自律運用: ゲート連鎖を審査とみなし、Environment の必須レビュアーを外す。
• 有人運用: Environment に必須レビュアーを設定し、ゲート連鎖は補助にする。

Step 7: リリースとして記録する

デプロイ結果とレビュー結果は、バージョンごとの GitHub Release に残す。

• タグはデプロイしたバージョンに対応させる（例: agent-v<version>）。
• 本文は review_report.py が生成したレビュー結果表をそのまま使う。
• 同じバージョンを再デプロイしたときは新規作成せず gh release edit で上書きする。
• Issue にメモを積む方式は採らない（Issue は課題管理のための場所であり、

デプロイ履歴を混ぜると課題一覧としての意味が失われる）。

flowchart TD
    A[ローカル編集] --> B[git commit]
    B -->|pre-commit| C[汎用化 + シークレット同期 + 漏洩検査]
    C --> D[PR]
    D --> E[決定論ゲート: review_sanitization]
    E --> F[自律レビューゲート連鎖 5 体]
    F -->|GO| G[既定ブランチへマージ]
    G --> H[デプロイ（プロダクトスキルの手順）]
    H --> I[GitHub Release にレビュー結果を記録]

検証チェックリスト

• [ ] .env と rendered / artifacts に該当するファイルが追跡されていない
• [ ] テンプレートに実 GUID・ARM パス・接続文字列・エンドポイントが無い
• [ ] .env.example にすべての変数がプレースホルダー付きで存在する
• [ ] 公開識別子が non_secret_vars に登録されている
• [ ] git config core.hooksPath .githooks が有効
• [ ] python scripts/review_sanitization.py が Pass し、必須チェックになっている
• [ ] ワークフローが permissions: を宣言し、contents: write がリリースジョブ限定
• [ ] 承認方式（自律 / 有人）が 1 つに決まっている
• [ ] デプロイのたびにリリースが作成／更新される

参考リンク

• レビューゲートの構成（ワークフロー・ルール一覧・プロンプト）
• CI / Git ホスティング別の構成（GitHub / Azure DevOps / その他）
• リポジトリ scaffold（.gitignore / hook / CI 定義）
• 異常系・トラブルシュート
• 環境変数サンプル（ALM 部分）