Forem: Habib Masri

Kiro CLI + ArgoCD MCP: Manage GitOps from Your Terminal

Habib Masri — Thu, 09 Apr 2026 15:17:27 +0000

Managing ArgoCD applications typically means writing Application YAML, configuring sync policies, and switching between the CLI and UI. It works, but there's a better way to do it.

With Kiro CLI and the ArgoCD MCP server, you can do all of that using natural language from your terminal — create apps, sync them, check health, view resource trees.

Deploying to Kubernetes Before GitOps

Before ArgoCD, deploying to Kubernetes was mostly manual. You'd write your manifests, run kubectl apply, and hope it works. A typical workflow:

Write Deployment, Service, ConfigMap YAML by hand
kubectl apply -f from your laptop
Verify the resources are running in the right namespace
Commit the manifests to Git (if you remember)
Repeat across environments, hoping cluster state and repo stay in sync

Some teams graduated to Helm charts, which helped with templating but didn't solve the drift problem. Others wrote custom CI/CD pipelines that ran kubectl apply on merge — better, but still push-based and fragile.

Then GitOps came along and flipped the model. Instead of pushing changes to the cluster, you declare the desired state in Git and let a controller pull it in. ArgoCD is the most popular implementation of this pattern — it watches your Git repo, compares it to what's running in the cluster, and reconciles the difference automatically.

The cluster state problem is solved. The day-to-day management — writing Application manifests, configuring sync policies, navigating the UI — is where an agentic approach can help.

What We're Building

By the end of this article, you'll have:

Kiro CLI connected to your ArgoCD instance via the ArgoCD MCP server
The ability to create, sync, and monitor ArgoCD applications using natural language directly from your terminal
A workflow for generating Application manifests with automated sync and health checks

The Setup

Prerequisites

An EKS cluster (or any Kubernetes cluster) with ArgoCD installed
An ArgoCD API token (docs for creating one)
Kiro CLI installed
Node.js v18+

If you don't have ArgoCD running yet, the quickest path on EKS is:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Then port-forward to access it locally:

kubectl port-forward svc/argocd-server -n argocd 8080:443

This forwards local port 8080 to ArgoCD's HTTPS port (443), so you'll access it at https://localhost:8080 — not http.

Getting Your ArgoCD API Token

You need an API token for the MCP server to authenticate with ArgoCD. From the ArgoCD UI:

Go to Settings → Accounts → admin
Click Generate New under Tokens
Copy the token — you'll need it in the next step

Or via CLI:

argocd account generate-token --account admin

Connecting Kiro CLI to ArgoCD

The ArgoCD MCP server is what makes this work. MCP (Model Context Protocol) lets Kiro communicate with external services through standardized tool interfaces. The ArgoCD MCP server exposes ArgoCD's API as tools that Kiro can call — list apps, create apps, sync, get resource trees, fetch logs, and more.

I prefer to wire the MCP server into a Kiro Custom Agent rather than a global mcp.json. This way the agent has a focused prompt, scoped tools, and the ArgoCD connection is self-contained — easy to share with the team or drop into any project.

Create .kiro/agents/argocd-agent.json in your project:

{
  "name": "argocd-agent",
  "description": "Manages ArgoCD applications via natural language — create, sync, monitor, and troubleshoot GitOps deployments",
  "prompt": "You are a GitOps specialist. You manage ArgoCD applications on Kubernetes clusters. Use the ArgoCD MCP tools to list, create, update, sync, and monitor applications. Always confirm destructive actions before executing them.",
  "mcpServers": {
    "argocd": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "https://localhost:8080",
        "ARGOCD_API_TOKEN": "<your-argocd-api-token>"
      }
    }
  },
  "tools": [
    "read",
    "@argocd"
  ],
  "allowedTools": [
    "read",
    "@argocd"
  ]
}

If your ArgoCD instance uses self-signed certificates (common with port-forwarding), add "NODE_TLS_REJECT_UNAUTHORIZED": "0" to the env block inside mcpServers.argocd.env. Only do this in development.

For safer use in production, add "MCP_READ_ONLY": "true" to the env block — this disables create, update, delete, and sync operations. See Read Only Mode.

Start Kiro CLI with the ArgoCD agent:

cd my-project
kiro-cli --agent argocd-agent

You can verify the MCP server loaded by running /mcp in the chat session — you should see argocd listed with its available tools.

Why a Custom Agent? Subagents and Context Management

There's another reason I use a custom agent instead of configuring all MCPs and tools in the default agent: subagents. In Kiro CLI, a parent agent can spawn custom agents as subagents — each running in its own context with its own tools. The subagent does its work in its own isolated context and returns only the result to the parent agent.

This matters for context window efficiency. Imagine a platform-engineer parent agent that handles broad infrastructure tasks. When it needs to interact with ArgoCD, it spawns argocd-agent as a subagent. The ArgoCD MCP tools, API responses, and resource trees only live in the subagent's context — they never bloat the parent's context window. Once the subagent returns the result, that context is freed.

You: Check if all apps are healthy, then review the Terraform plan for the new VPC

platform-engineer agent:
  → spawns argocd-agent: "List all applications and check their health"
    ← returns: "3 apps, all Healthy and Synced"
  → reviews Terraform plan with its own tools (clean context, no ArgoCD noise)

You can even pre-trust the ArgoCD agent so it runs without permission prompts:

{
  "name": "platform-engineer",
  "description": "Parent agent for infrastructure and platform tasks",
  "tools": ["read", "write", "shell", "aws", "subagent"],
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["argocd-agent", "terraform-agent"],
      "trustedAgents": ["argocd-agent"]
    }
  }
}

This is the real payoff of defining ArgoCD as a custom agent — it becomes a composable, context-efficient building block in a larger workflow.

Creating an ArgoCD Application with Natural Language

Instead of writing an Application manifest by hand, just tell Kiro what you want:

Create a new ArgoCD application called guestbook that deploys from the repo https://github.com/argoproj/argocd-example-apps, path guestbook, targeting the default namespace on the in-cluster destination

Kiro uses the create_application Tool from the ArgoCD MCP server. Kiro handles the API call and creates the application directly in ArgoCD.

The equivalent YAML that ArgoCD creates under the hood looks like this:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Here's what each field does:

project: The ArgoCD project this app belongs to. default works for most cases.
source.repoURL: The Git repository containing your manifests.
source.path: The directory within the repo where the Kubernetes manifests live.
source.targetRevision: Which branch/tag/commit to track. HEAD follows the default branch.
destination.server: The cluster to deploy to. https://kubernetes.default.svc means "this cluster."
destination.namespace: Where the resources get created.

Adding Automated Sync

By default, ArgoCD applications are created without auto-sync — you have to manually trigger syncs. That's fine for production, but for dev/staging environments, you usually want changes to deploy automatically when you push to Git.

Update the guestbook application to enable automated sync with self-healing and auto-pruning

Kiro calls update_application and configures the sync policy. Here's what those settings mean:

Automated sync: ArgoCD automatically syncs when it detects the Git repo has changed
Self-healing: If someone manually changes a resource in the cluster (kubectl edit, etc.), ArgoCD reverts it back to match Git
Auto-prune: If you remove a resource from Git, ArgoCD deletes it from the cluster too

The equivalent sync policy in YAML:

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Checking Application Health

Once the app is synced, you want to know if it's actually healthy — are the pods running? Did the deployment roll out successfully?

Check the health of the guestbook application

Kiro calls get_application and returns the sync status, health status, and any conditions. You'll see something like:

Sync Status: Synced
Health Status: Healthy
Resources: Deployment (Healthy), Service (Healthy)

If something is wrong, you can dig deeper:

Show me the resource tree for the guestbook application

This calls get_application_resource_tree and shows the full hierarchy — the Application owns a Deployment, which owns a ReplicaSet, which owns Pods. If a pod is in CrashLoopBackOff, you'll see it here.

Get the logs for the failing pod in the guestbook application

Kiro calls get_application_workload_logs and pulls the logs directly, so you don't need to kubectl logs into the right namespace and pod name.

Syncing and Monitoring

When you need to manually trigger a sync (maybe you have auto-sync disabled in production):

Sync the guestbook application

Show me which applications are out of sync

List all ArgoCD applications in my cluster

Each of these maps to a specific MCP tool (sync_application, list_applications, etc.) and Kiro handles the API calls behind the scenes.

The Full Workflow

Here's what a typical session looks like, end to end:

You: List all ArgoCD applications
Kiro: [calls list_applications] You have 3 applications: 
      frontend (Synced/Healthy), backend (OutOfSync/Healthy), 
      monitoring (Synced/Degraded)

You: Sync the backend application
Kiro: [calls sync_application] Sync initiated for backend. 
      Revision: abc123f

You: Check the health of the monitoring application
Kiro: [calls get_application] monitoring is Degraded. 
      The prometheus-server Deployment has 0/1 ready replicas.

You: Show me the logs for the prometheus-server in monitoring
Kiro: [calls get_application_workload_logs] 
      Error: no persistent volume claim found...

All from one terminal session, instead of remembering commands like argocd app get monitoring -o yaml | grep health.

Try It Yourself

Install Kiro CLI:
- macOS/Linux: curl -fsSL https://cli.kiro.dev/install | bash
- Windows (PowerShell): irm 'https://cli.kiro.dev/install.ps1' | iex
Set up the ArgoCD MCP server config as shown above
Start a chat session with kiro-cli and try: List all ArgoCD applications in my cluster

If you've been managing ArgoCD through the UI or memorizing CLI flags, try it on a staging cluster and see how it feels.

Generating GitHub Actions Workflows with Kiro

Habib Masri — Tue, 10 Mar 2026 10:23:03 +0000

I had a Python Lambda project sitting in a repo with zero CI/CD. No pipeline, no automation, just sam deploy from my laptop like it's 2019.

So I used Kiro to generate a complete GitHub Actions pipeline — build, test, deploy — and watched it go green on the first push. Okay fine, the third push. But who's
counting.

Here's exactly how I did it.

The Setup

The project is simple on purpose. A Python Lambda function behind API Gateway, deployed with AWS SAM:

├── src/
│   └── app.py              # Lambda handler
├── tests/
│   └── test_app.py         # pytest unit tests
├── template.yaml            # SAM template
├── samconfig.toml           # SAM deploy config
└── .kiro/skills/
    └── github-actions-cicd/ # Kiro skill

The Lambda handler uses Powertools for AWS Lambda (Python) — a developer toolkit that gives you structured JSON logging, tracing, and metrics out of the box. I'm only using the Logger here, which gives me structured logs with correlation IDs and cold start tracking with a single decorator:

from aws_lambda_powertools import Logger

logger = Logger()

@logger.inject_lambda_context
def lambda_handler(event, context):
    logger.info("Root endpoint called")
    # ... route handling

Three pytest tests cover the routes. Minimal, but the focus here is the pipeline, not the app.

Teaching Kiro How I Want My Pipelines Built

Before generating the workflow, I asked Kiro to create a Skill — a reusable instruction package that tells Kiro how to do something, not just what to do. Skills follow the open Agent Skills standard, so they're shareable across tools and teams.

Kiro uses progressive disclosure with skills — it loads only the name and description at startup, activates the full instructions when your request matches, and pulls in reference files only when needed. No wasted tokens in the context window.

"Create a Kiro skill for generating GitHub Actions CI/CD workflows for Python Lambda projects using SAM. It should use three jobs: test, build, deploy. Use OIDC for AWS auth, pip caching, and GitHub Environments."

Kiro generated .kiro/skills/github-actions-cicd/SKILL.md:

---
name: github-actions-cicd
description: Generate GitHub Actions CI/CD workflows for Python Lambda 
  projects using SAM. Use when creating pipelines, adding CI/CD, 
  generating workflow YAML, or deploying Lambda functions with 
  GitHub Actions.
---

## Workflow Structure

Generate GitHub Actions workflows with three jobs:

1. **build** — Run `sam build` to compile the SAM application
2. **test** — Install dependencies and run `pytest`
3. **deploy** — Run `sam deploy` to deploy to AWS (only on push to `main`)

## AWS Authentication

Always use OIDC for AWS credentials via 
`aws-actions/configure-aws-credentials`. Never use static access keys.

## Caching

Use `actions/cache` for pip dependencies.

## Environment Strategy

- `production` environment: deploys on push to `main` branch
- Use GitHub Environments for secrets and protection rules

I also added reference files under references/ with specific patterns for SAM deploys, matrix builds, and security hardening. Kiro loads these only when the instructions point to them — keeping things lean.

The skill is committed to the repo, so anyone who clones it gets the same behavior. That's the power of skills — they're portable and version-controlled.

Full docs on skills: kiro.dev/docs/cli/skills

The Generated Workflow

With the skill in place, I asked Kiro to generate a GitHub Actions workflow. Here are some of the prompts I used:

"Generate a GitHub Actions CI/CD workflow for this project"

That gave me the base pipeline. Then I iterated:

"Add pip caching to speed up the test job"

"Add a matrix build to test on Python 3.11 and 3.12"

"Split the deploy into its own job that only runs on push to main, using OIDC for AWS auth"

The skill activated automatically each time — no special command needed — and Kiro followed the conventions I defined. Here's the structure of the final workflow (full YAML in the repo):

name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]
    steps:
      # checkout, setup python, pip cache, install deps, pytest

  build:
    needs: test
    steps:
      # checkout, setup SAM, sam build, upload artifact

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production
    permissions:
      id-token: write
      contents: read
    steps:
      # checkout, download artifact, setup SAM, configure AWS creds (OIDC), sam deploy

Let me break down what's happening.

Walking Through the Pipeline

Job 1: Test

test:
  runs-on: ubuntu-latest
  strategy:
    matrix:
      python-version: ["3.11", "3.12"]

Runs on every push and PR. The matrix build tests against Python 3.11 and 3.12 in parallel — so you catch version-specific issues early.

Pip caching uses actions/cache keyed on the OS, Python version, and a hash of requirements.txt. Second runs are noticeably faster.

Job 2: Build

build:
  needs: test

Only runs after tests pass. Runs sam build and uploads the .aws-sam/ output as a GitHub artifact. The deploy job downloads this artifact instead of rebuilding — keeping the deploy fast and ensuring you deploy exactly what you built.

Job 3: Deploy

deploy:
  needs: build
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  environment: production
  permissions:
    id-token: write
    contents: read

This is where it gets interesting. The deploy job:

Only runs on push to main — PRs trigger test + build but never deploy
Uses a GitHub Environment (production) — you can add protection rules like required reviewers
Authenticates via OIDC — no static AWS keys anywhere

Setting Up OIDC Authentication (No Static Keys)

This is the part most people skip or get wrong. Instead of storing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as GitHub secrets (please don't), we use OpenID Connect to get short-lived credentials.

Here's the setup:

1. Create the OIDC identity provider in IAM:

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

2. Create an IAM role with a trust policy scoped to your repo + environment:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:<OWNER>/<REPO>:environment:production"
        }
      }
    }
  ]
}

The sub condition is critical — it locks the role down to your repo's production environment. Nothing else can assume it.

3. Add the secret and variable in GitHub:

gh secret set AWS_ROLE_TO_ASSUME --body "arn:aws:iam::<ACCOUNT_ID>:role/GitHubActions-KiroDemo"
gh variable set AWS_REGION --body "us-east-1"

Notice AWS_ROLE_TO_ASSUME is a secret (sensitive) while AWS_REGION is a variable (not sensitive).

Full guide: Configuring OpenID Connect in AWS

The Result

Push to main, and the pipeline runs:

✅ test (3.11) — 8s
✅ test (3.12) — 11s
✅ build — 18s
✅ deploy — deploys to AWS via SAM

Three jobs, zero static credentials, matrix testing, pip caching, artifact passing between jobs. All generated by Kiro with a skill that encodes how I want my pipelines built.

What I'd Add Next

The pipeline is intentionally simple, but here's what you could ask Kiro to add:

Multi-environment deploys — staging on develop, production on main, each with their own GitHub Environment and IAM role
Linting — add ruff or flake8 as a step in the test job
SAM validate — run sam validate in the build job before sam build
Notifications — Slack or Teams notification on deploy success/failure

Each of these is a single prompt to Kiro — and because the skill is in place, it'll follow the same conventions every time.

Try It Yourself

The full repo is here: github.com/habibmasri/kiro-cli-github-actions

Clone it, install Kiro CLI, and try asking it to modify the pipeline. The skill is included — it'll just work.