julianobarbosa/skills/argocd

ArgoCD Skill

Complete ArgoCD operations via REST API and CLI with bearer token authentication.

Authentication Setup

Generate and use bearer tokens for all operations:

# Generate token (requires existing login)
argocd login $ARGOCD_SERVER --username admin --password $ARGOCD_PASSWORD
ARGOCD_TOKEN=$(argocd account generate-token)

# Or generate for service account
ARGOCD_TOKEN=$(argocd account generate-token --account cibot --expires-in 7d)

# Export for subsequent commands
export ARGOCD_SERVER="argocd.example.com"
export ARGOCD_AUTH_TOKEN="$ARGOCD_TOKEN"

Service account setup (in argocd-cm ConfigMap):

data:
  accounts.cibot: apiKey,login
  accounts.cibot.enabled: "true"

REST API Pattern

All API calls use this pattern:

curl -s -H "Authorization: Bearer $ARGOCD_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  "https://$ARGOCD_SERVER/api/v1/{endpoint}"

Use the helper script at scripts/argocd-api.sh for common operations.

Quick Reference

Applications

# List all applications
argocd app list -o json

# Create application
argocd app create myapp \
  --repo https://github.com/org/repo.git \
  --path manifests \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --sync-policy automated \
  --auto-prune \
  --self-heal

# Sync with options
argocd app sync myapp --prune --force --timeout 300

# Sync specific resources only
argocd app sync myapp --resource apps:Deployment:nginx

# Dry run
argocd app sync myapp --dry-run

# Wait for health
argocd app wait myapp --health --sync --timeout 300

# Get status
argocd app get myapp -o json | jq '{health: .status.health.status, sync: .status.sync.status}'

# Rollback
argocd app history myapp
argocd app rollback myapp 2

# Delete (cascade deletes resources)
argocd app delete myapp --cascade -y

# Terminate running operation
argocd app terminate-op myapp

ApplicationSets

# Create/update ApplicationSet
argocd appset create appset.yaml --upsert

# List
argocd appset list

# Get details
argocd appset get myappset -o yaml

# Delete
argocd appset delete myappset -y

Projects

# Create project
argocd proj create myproject -d https://kubernetes.default.svc,default -s https://github.com/org/*

# Add destinations/sources
argocd proj add-destination myproject https://kubernetes.default.svc 'team-*'
argocd proj add-source myproject 'https://github.com/org/*'

# Manage roles
argocd proj role create myproject deployer
argocd proj role add-policy myproject deployer -a sync -p allow -o '*'
argocd proj role add-group myproject deployer my-sso-group

# Generate role token
argocd proj role create-token myproject deployer --expires-in 24h

# Sync windows
argocd proj windows add myproject \
  --kind allow --schedule "0 22 * * *" --duration 2h
argocd proj windows list myproject

Repositories

# Add HTTPS repo with token
argocd repo add https://github.com/org/repo --username git --password $GH_TOKEN

# Add SSH repo
argocd repo add [email protected]:org/repo.git --ssh-private-key-path ~/.ssh/id_rsa

# Add Helm repo
argocd repo add https://charts.example.com --type helm --name myrepo

# Add OCI registry
argocd repo add registry.example.com \
  --type helm --enable-oci --username user --password pass

# Credential template (applies to matching repos)
argocd repocreds add https://github.com/myorg/ --username git --password $TOKEN

# List/remove
argocd repo list
argocd repo rm https://github.com/org/repo

Clusters

# Add cluster from kubeconfig context
argocd cluster add my-context --name production

# List clusters
argocd cluster list

# Get cluster details
argocd cluster get https://production.example.com

# Rotate credentials
argocd cluster rotate-auth production

# Remove cluster
argocd cluster rm https://production.example.com

Accounts

# List accounts
argocd account list

# Generate token
argocd account generate-token --account cibot --expires-in 7d --id deploy-token

# Check permissions
argocd account can-i sync applications '*'
argocd account can-i get applications 'myproject/*'

# Update password
argocd account update-password --account admin

# Get user info
argocd account get-user-info

REST API Examples

See references/api-reference.md for complete endpoint documentation.

Create Application via API

curl -X POST -H "Authorization: Bearer $ARGOCD_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  "https://$ARGOCD_SERVER/api/v1/applications" \
  -d '{
    "metadata": {"name": "myapp", "namespace": "argocd"},
    "spec": {
      "project": "default",
      "source": {
        "repoURL": "https://github.com/org/repo.git",
        "path": "manifests",
        "targetRevision": "HEAD"
      },
      "destination": {
        "server": "https://kubernetes.default.svc",
        "namespace": "default"
      },
      "syncPolicy": {
        "automated": {"prune": true, "selfHeal": true},
        "syncOptions": ["CreateNamespace=true"]
      }
    }
  }'

Sync Application via API

curl -X POST -H "Authorization: Bearer $ARGOCD_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  "https://$ARGOCD_SERVER/api/v1/applications/myapp/sync" \
  -d '{
    "revision": "HEAD",
    "prune": true,
    "dryRun": false,
    "strategy": {"hook": {}},
    "syncOptions": {"items": ["CreateNamespace=true"]}
  }'

Get Application Status

curl -s -H "Authorization: Bearer $ARGOCD_AUTH_TOKEN" \
  "https://$ARGOCD_SERVER/api/v1/applications/myapp" | \
  jq '{name: .metadata.name, health: .status.health.status, sync: .status.sync.status}'

Application Spec Reference

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default

  source:
    repoURL: https://github.com/org/repo.git
    targetRevision: HEAD
    path: manifests

    # Helm options
    helm:
      releaseName: my-release
      valueFiles: [values.yaml, values-prod.yaml]
      parameters:
        - name: image.tag
          value: v1.0.0

    # Kustomize options
    kustomize:
      namePrefix: prod-
      images: [gcr.io/image:v1.0.0]

  destination:
    server: https://kubernetes.default.svc
    namespace: default

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers: [/spec/replicas]

ApplicationSet Generators

See references/api-reference.md for complete generator patterns.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
  namespace: argocd
spec:
  generators:
    # List generator
    - list:
        elements:
          - cluster: dev
            url: https://dev.example.com
          - cluster: prod
            url: https://prod.example.com

    # Cluster generator
    - clusters:
        selector:
          matchLabels:
            environment: production

    # Git directory generator
    - git:
        repoURL: https://github.com/org/apps.git
        directories:
          - path: apps/*

    # Matrix generator (combine two generators)
    - matrix:
        generators:
          - clusters: {}
          - git:
              repoURL: https://github.com/org/apps.git
              directories: [{path: apps/*}]

  template:
    metadata:
      name: '{{.cluster}}-{{.path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/apps.git
        targetRevision: HEAD
        path: '{{.path.path}}'
      destination:
        server: '{{.url}}'
        namespace: '{{.path.basename}}'

Sync Options Reference

| Option | Description | |--------|-------------| | Prune=true | Delete resources not in Git | | PruneLast=true | Prune after sync completes | | Replace=true | Use replace instead of apply | | ServerSideApply=true | Use server-side apply | | CreateNamespace=true | Create namespace if missing | | ApplyOutOfSyncOnly=true | Only sync changed resources | | Validate=false | Skip kubectl validation | | Force=true | Force resource replacement | | RespectIgnoreDifferences=true | Respect ignoreDifferences on sync |

Resource Hooks and Waves

metadata:
  annotations:
    # Sync wave (lower = earlier)
    argocd.argoproj.io/sync-wave: "-1"

    # Hook phase
    argocd.argoproj.io/hook: PreSync|Sync|PostSync|SyncFail|PostDelete

    # Hook deletion policy
    argocd.argoproj.io/hook-delete-policy: HookSucceeded|HookFailed|BeforeHookCreation

Health Status Values

| Status | Description | |--------|-------------| | Healthy | Resource running correctly | | Progressing | Deployment in progress | | Degraded | Health check failed | | Suspended | Resource paused | | Missing | Resource doesn't exist | | Unknown | Cannot determine health |

CLI Global Flags

| Flag | Description | |------|-------------| | --server | ArgoCD server address | | --auth-token | Bearer token | | --grpc-web | Use gRPC-web (for proxies) | | --insecure | Skip TLS verification | | --plaintext | Disable TLS | | --config | Config file path | | -o json/yaml/wide | Output format |

Error Handling

# Check if app exists before operations
if argocd app get myapp &>/dev/null; then
  argocd app sync myapp
else
  argocd app create myapp ...
fi

# Wait with timeout and handle failure
if ! argocd app wait myapp --health --timeout 300; then
  echo "App failed to become healthy"
  argocd app get myapp
  exit 1
fi

# Idempotent upsert pattern
argocd app create myapp --upsert ...
argocd repo add https://repo --upsert ...

Common Workflows

Deploy and Wait Pattern

argocd app sync myapp --prune --async
argocd app wait myapp --health --sync --timeout 300

Canary/Blue-Green with Argo Rollouts

# Promote rollout
argocd app actions run myapp promote --kind Rollout --resource-name my-rollout

Multi-Cluster Deployment

# Register clusters
argocd cluster add dev-context --name dev
argocd cluster add prod-context --name prod

# Use ApplicationSet with cluster generator

Admin Operations

# Get initial admin password
argocd admin initial-password -n argocd

# Export all resources for backup
argocd admin export > backup.yaml

# Import from backup
argocd admin import < backup.yaml

# Start local dashboard (core mode)
argocd admin dashboard

# Validate RBAC policy
argocd admin settings rbac validate --policy-file policy.csv

# Test RBAC permission
argocd admin settings rbac can role:developer sync applications 'myproject/*'

# Notification management
argocd admin notifications template list
argocd admin notifications trigger list

Troubleshooting Quick Reference

# Check diff for out-of-sync apps
argocd app diff myapp

# Force refresh from Git
argocd app get myapp --hard-refresh

# View detailed sync operation
argocd app get myapp --show-operation

# Check application conditions
argocd app get myapp -o json | jq '.status.conditions'

# Terminate stuck sync
argocd app terminate-op myapp

# Check controller logs
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller --tail=100

# Apps not healthy
argocd app list -o json | \
  jq -r '.items[] | select(.status.health.status != "Healthy") | .metadata.name'

# Apps out of sync
argocd app list -o json | \
  jq -r '.items[] | select(.status.sync.status != "Synced") | .metadata.name'

For complete API endpoint documentation, see references/api-reference.md. For complete CLI command reference, see references/cli-reference.md. For troubleshooting guide, see references/troubleshooting.md.

---

Absorbed sub-skills (post-consolidation)

This skill now subsumes the former argocd-command and argocd-review skills. Their original SKILL.md content (still useful as deep reference) lives under References/:

| Subject | Path | |---------|------| | Hypera/Cafehyna local cluster context (kubeconfig, port-forward, aliases) | References/command-cafehyna.md + References/command-workflows/ + References/command-tools/ | | Application review, diff, rollback, history, sync troubleshooting | References/review.md + References/review-workflows/ + References/review-tools/ |

For multi-cluster ApplicationSets, Image Updater, cluster bootstrapping, and workload onboarding, see the sibling argocd-advanced skill. For canary / blue-green / promotion, see progressive-delivery.

---

Gotchas

• OutOfSync with empty diff: Usually a Helm chart releaseName change or kustomize hash mismatch after a CRD upgrade. argocd app diff shows nothing — run argocd app manifests to see the rendered output.
• ignoreDifferences silently ignored under SSA: With Server-Side Diff enabled, schema-validation errors on unknown fields (e.g. Job podReplacementPolicy on K8s 1.29+) fire before ignoreDifferences runs. Disable SSA per-app via argocd.argoproj.io/compare-options: ServerSideDiff=false.
• --cascade deletes the namespace too if you created it via CreateNamespace=true. Use --cascade=false to detach the Application while keeping workloads.
• Tokens cannot be revoked individually — only by deleting the account or rotating the JWT signing key. Always pass --id to generate-token so you can audit which token is which.
• argocd app sync on an automated-sync app is a no-op if the controller already attempted a sync this poll cycle. Add --force or temporarily disable auto-sync to push through.
• finalizers: [resources-finalizer.argocd.argoproj.io] is required for cascade delete to actually remove cluster resources. Without it, deleting the Application orphans everything in the destination namespace.