gitops-workflow

gitops-workflow スキルの概要

gitops-workflow で実際にできること

gitops-workflow スキルは、ArgoCD または Flux を使って、Kubernetes 向けの実践的な GitOps 運用モデルを設計・実装するのに役立ちます。単に「CD ツールを入れる」ためのものではなく、Git をクラスター状態の信頼できる唯一の情報源として扱い、reconciliation を自動化し、デプロイ、drift 修正、sync の挙動、変更承認を日常運用でどう回すかまで定義するのが本来の役割です。

このスキルが最も向いているケース

この gitops-workflow skill は、Git ベースの Kubernetes デリバリーを採用する前提があり、整理された出発点を必要としている platform engineer、SRE、DevOps チーム、AI ユーザーに最適です。特に、ArgoCD 型のアプリケーション中心の運用と、Flux 型の controller 主導の reconciliation のどちらを選ぶか検討している場合や、抽象的な GitOps 理論ではなく、実際のデプロイ方針の例が欲しい場合に有効です。

一般的な GitOps プロンプトと何が違うのか

一般的なプロンプトでも GitOps の原則は説明できます。一方 gitops-workflow は、実運用に載せやすいパターンが必要なときにより有用です。OpenGitOps の原則、ArgoCD の導入パス、リポジトリ構成の指針、ArgoCD と Flux の両方に対する具体的な sync policy 例が含まれているためです。収録されている参照資料により、表面的に repo を眺めるだけよりも、Deployment 作業に直結するアウトプットを得やすくなります。

このスキルが代わりにやってくれるわけではないこと

このスキルは、クラスター構成、セキュリティルール、secret 戦略、promotion モデルを自動で発見してくれるわけではありません。環境に関する判断は引き続き自分で渡す必要があります。たとえば、ArgoCD か Flux か、single-cluster か multi-cluster か、namespace 戦略、アプリ配置、sync を manual にするか automated にするか、あるいは time window で制限するか、といった点です。

gitops-workflow スキルの使い方

gitops-workflow スキルをインストールする

リポジトリから次のコマンドでインストールします。

npx skills add https://github.com/wshobson/agents --skill gitops-workflow

その後、Kubernetes Deployment 向けの GitOps ワークフローを計画または生成したいタイミングで、agent 環境から呼び出します。

最初に読むべきファイル

最短で全体像をつかむなら、まずは次の順番で確認してください。

1. plugins/kubernetes-operations/skills/gitops-workflow/SKILL.md
2. plugins/kubernetes-operations/skills/gitops-workflow/references/argocd-setup.md
3. plugins/kubernetes-operations/skills/gitops-workflow/references/sync-policies.md

この読む順番には意味があります。メインの skill は対象範囲を説明し、ArgoCD の reference は bootstrap とアクセス方法を扱い、sync policy の reference は安全性と自動化品質に直結する運用上の調整項目を示しています。

プロンプト前に決めておくべき重要な判断

gitops-workflow を使う前に、どの controller 系統を前提に出力してほしいかを決めておきましょう。

• アプリケーション中心の強いワークフロー、UI による可視性、明示的な sync 制御が欲しいなら ArgoCD
• GitOps コンポーネントを controller ネイティブに組み合わせたい、より Kubernetes resource 主導のモデルが欲しいなら Flux

ここを指定しないと、出力は汎用的すぎて deployment-ready になりにくい傾向があります。

有用な出力に必要な入力情報

gitops-workflow usage の質は、入力情報の具体性に大きく左右されます。少なくとも次を渡してください。

• Kubernetes distribution と version
• 対象 controller: ArgoCD または Flux
• クラスター数と環境数
• repo 構成の希望: mono-repo、config repo、app-per-repo
• deployment 戦略: manual sync、auto-sync、progressive rollout、sync windows
• secret の扱い方に関する前提
• namespace を自動作成すべきかどうか
• dev -> staging -> prod のような promotion path

これらがない場合、このスキルが返せるのは実装可能な計画ではなく、広めの GitOps ガイドにとどまります。

ざっくりした目的を強いプロンプトに変える

弱いプロンプト:

Set up GitOps for my cluster.

より良いプロンプト:

Use the gitops-workflow skill to design an ArgoCD-based GitOps workflow for a 3-environment EKS setup. We want app manifests in Git, automated sync in dev, manual approval in prod, pruning enabled, self-heal on, and namespace auto-creation where safe. Propose repo structure, ArgoCD install method, Application or ApplicationSet approach, and example sync policies.

これが機能しやすい理由は次のとおりです。

• ツール選定が固定されている
• 環境構成が定義されている
• reconciliation の振る舞いが明示されている
• 理論ではなく、構造的な成果物を求めている

インストールだけでなく、リポジトリ設計にも使う

gitops-workflow for Deployment の価値が最も高い使い方のひとつが、リポジトリ構成の設計です。元資料には GitOps repo layout が含まれており、実際に導入を止めがちなのもこの部分です。ArgoCD の入れ方は分かっていても、apps、bases、overlays、環境別 config をどう整理すれば保守しやすいかで詰まるチームは少なくありません。

次の点は明示的に依頼すると効果的です。

• directory structure
• promotion flow
• app onboarding pattern
• cluster / environment の分離方法
• sync ownership boundaries

含まれている ArgoCD の導入パスは慎重に使う

reference には、ArgoCD の複数の導入方法が含まれています。

• standard manifest install
• high availability install
• Helm install

これは gitops-workflow install の判断に役立ちます。評価用途や社内向けクラスターなら、standard install で十分なことが多いでしょう。一方、本番 control plane では、HA 構成や Helm 管理の導入のほうが現実的なケースが多くあります。チーム規模、求める稼働性、platform コンポーネントをすでに Helm 管理しているかどうかを前提に、おすすめ案を出すようスキルに依頼してください。

sync policy の判断は明示的に依頼する

このスキルで最も実務に効く reference は、sync policy のガイダンスです。本番の挙動に関わる出力が欲しいなら、次の項目について具体的な policy 提案を求めてください。

• prune
• selfHeal
• allowEmpty
• retry policy
• sync windows
• CreateNamespace=true
• Flux における reconciliation intervals

これらの設定が、実クラスターにおいて GitOps を「安全」「うるさい」「壊れやすい」「信頼できる」のどれに感じるかを左右します。

初回利用におすすめの進め方

最初の一巡としては、次の流れが適しています。

1. gitops-workflow skill をインストールする。
2. SKILL.md を読み、スコープと対応パターンを把握する。
3. config を生成する前に references/sync-policies.md を読む。
4. まずアーキテクチャ計画を出させる。
5. 続けて manifests、repo layout、rollout policy の例を出させる。
6. その出力を RBAC、secret、promotion の制約に照らして見直す。
7. その後で初めて production-ready YAML を依頼する。

この順序にすると、運用方針を決める前に manifest を生成してしまう、よくある失敗を減らせます。

実用的で使いやすいプロンプトパターン

有効なプロンプトの形としては、たとえば次のようなものがあります。

• Use gitops-workflow to compare ArgoCD and Flux for our Kubernetes Deployment model.
• Use gitops-workflow to propose a GitOps repository structure for 20 services across dev, staging, and prod.
• Use gitops-workflow to generate ArgoCD sync policies that balance fast dev deploys with guarded production releases.
• Use gitops-workflow to review whether our current GitOps setup violates OpenGitOps principles.

これらが強いのは、判断、構造、評価結果のいずれかを明確に求めているからです。

導入初期に早めに洗い出すべき障害要因

次のリスクは、早い段階で指摘させるようにしてください。

• 暗号化や external secret のパターンが未定義なまま secrets を Git に保存している
• ownership boundaries を確認する前に本番で auto-prune を有効化している
• 明確な promotion モデルがないまま app source と environment state を混在させている
• 運用モデルではなく好みだけで ArgoCD か Flux を選んでいる
• GitOps が CI を補完するのではなく置き換えるものだと誤解している

このスキルは、rollout 前にこうした設計上の選択を炙り出す用途で使うと、最も価値が出ます。

gitops-workflow スキル FAQ

gitops-workflow は初心者にも向いていますか？

はい、基本的な Kubernetes object を理解していて、整理された gitops-workflow guide が欲しい人には向いています。逆に、namespace、Deployments、Services、ingress をまだ学んでいる段階なら適しません。このスキルは GitOps を採用方針として決めていることを前提にしており、Kubernetes の基礎ではなく実装パターンに焦点を当てています。

gitops-workflow は ArgoCD 専用ですか？

いいえ。このスキルは ArgoCD と Flux の両方を扱います。実際には、reference は ArgoCD の bootstrap にやや厚く、sync の例は両エコシステム向けに含まれています。Flux 特化の出力が欲しい場合は、プロンプトで明示してください。

どんな場合は gitops-workflow を使うべきではありませんか？

gitops-workflow は、Kubernetes 以外のデプロイ自動化、命令型のリリーススクリプト、あるいは単体で完結する secrets-management ソリューションが必要な場合には向きません。また、チームが Git を deployment control plane として扱う準備ができていない場合も相性はよくありません。

AI に直接 GitOps の相談をするより、どこが優れていますか？

gitops-workflow skill は、agent に対してより絞られたスコープ、明確な Kubernetes GitOps の文脈、そして ArgoCD setup や sync policy といった具体的な参照資料を与えます。その結果、推測に頼る部分が減り、汎用的なベストプラクティスの水増し説明も少ない回答になりやすいです。

gitops-workflow には本番で安全なデフォルト設定が含まれていますか？

それだけで本番安全になるわけではありません。例やパターンは含まれていますが、本番で安全な設定は環境依存です。たとえば prune、selfHeal、retry の挙動、sync windows はすべて文脈に左右されます。このスキルは auto-approved な設定ソースではなく、判断材料として使うべきです。

gitops-workflow は multi-cluster の Deployment 設計にも使えますか？

はい。複数クラスター向けの repo layout、環境分離、controller の振る舞いを設計したい場合に非常に相性がよいです。クラスター数、tenancy model、ワークロードが共通なのか環境固有なのかを明示すると、より実践的な提案になります。

gitops-workflow スキルを改善する方法

YAML を求める前に環境情報を渡す

gitops-workflow usage を最も手早く改善する方法は、まず文脈を渡し、その後で manifests を求めることです。入力情報として有効なのは次のようなものです。

• cloud か on-prem か
• ingress パターン
• クラスター数
• 環境間の promotion ルール
• rollback に対する期待
• drift correction を自動にすべきかどうか

こうした情報があると、deployment モデルに構造的に合った出力になりやすくなります。

推奨だけでなく、トレードオフも尋ねる

次のように聞くのではなく:

Recommend ArgoCD settings.

次のように依頼してください:

Use gitops-workflow to recommend ArgoCD sync settings for prod, and explain the tradeoffs of prune, selfHeal, retry, and sync windows for a regulated environment.

GitOps の設定は単なる syntax ではなく、運用ポリシーの選択だからです。トレードオフまで出させることで、意思決定の質が上がります。

bootstrap と定常運用を分けて答えさせる

よくある失敗は、control plane の導入、アプリの onboarding、promotion policy が、ひとつの曖昧な回答に混ざってしまうことです。結果を改善したいなら、次の 3 つを別々の出力として依頼してください。

1. bootstrap steps
2. repository structure
3. ongoing deployment workflow

この分け方のほうが、実際のチームが GitOps を導入するときの進め方に合っています。

現在の repo 構成例を渡す

すでに repository があるなら、簡略化した tree を貼り付けましょう。gitops-workflow skill は、現在 base/overlays を使っているのか、environment folder 方式なのか、app folder 方式なのか、あるいは application と infrastructure manifests が混在しているのかが見えると、格段に具体的な助言ができます。

リスクレベルに応じた policy 例を求める

「best sync policy」を求めるのではなく、次のように依頼してください。

• 速度重視の dev policy
• 検証重視の staging policy
• 安全性重視の prod policy

こうすると出力がより実務向きになります。特に auto-sync、pruning、manual gate 周りは、環境ごとに設定を変えるべきだからです。

最初の回答を実際の制約で検証する

最初の出力を受け取ったら、次のような具体的制約を追加して再度詰めていきます。

• We cannot expose the ArgoCD UI publicly.
• Prod namespaces must be pre-created by platform admins.
• Application teams can edit app manifests but not cluster-level resources.
• We need a change freeze window overnight.

このやり方で、gitops-workflow の出力を汎用ガイドから、実際にチームが運用できる operating model に近づけられます。

reference を使って弱い回答を引き締める

回答が広すぎると感じたら、repo 内でも特に強い資料に立ち返らせてください。

• references/argocd-setup.md を前提に、どの installation を選ぶべきかを聞く
• references/sync-policies.md を前提に、具体的な policy 例を求める

こうすることで、一般的な DevOps 論に流れず、元の source に根ざした回答を引き出せます。