Managing Atlantis

Atlantis Management Skill

Manage and inspect Atlantis PR-based Terraform automation, projects, and workflows.

MANDATORY: Discovery-First Pattern

Always check server status and active locks before triggering plans or applies.

Phase 1: Discovery

#!/bin/bash

echo "=== Atlantis Server Status ==="
curl -s "${ATLANTIS_URL}/status" 2>/dev/null | jq '.' || \
curl -s "${ATLANTIS_URL}/healthz" 2>/dev/null

echo ""
echo "=== Active Locks ==="
curl -s -H "X-Atlantis-Token: $ATLANTIS_TOKEN" \
    "${ATLANTIS_URL}/api/locks" 2>/dev/null | jq '
    .[] | {
        repo: .repo_full_name,
        workspace: .workspace,
        pull_num: .pull.num,
        locked_by: .pull.author,
        time: .time
    }
' | head -30

echo ""
echo "=== Server Configuration ==="
curl -s "${ATLANTIS_URL}/api/server-config" 2>/dev/null | jq '{
    allow_fork_prs: .allow_fork_prs,
    auto_merge: .auto_merge,
    default_tf_version: .default_tf_version,
    repo_allowlist: .repo_allowlist
}' 2>/dev/null || echo "Server config API not available"

Core Helper Functions

#!/bin/bash

# Atlantis API wrapper
atlantis_api() {
    local method="${1:-GET}"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "X-Atlantis-Token: $ATLANTIS_TOKEN" \
            -H "Content-Type: application/json" \
            "${ATLANTIS_URL}/api/${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "X-Atlantis-Token: $ATLANTIS_TOKEN" \
            "${ATLANTIS_URL}/api/${endpoint}"
    fi
}

# GitHub/GitLab comment helper for PR commands
atlantis_comment() {
    echo "Use these PR comments:"
    echo "  atlantis plan [-w workspace] [-d directory]"
    echo "  atlantis apply [-w workspace] [-d directory]"
    echo "  atlantis unlock"
}

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use API endpoints for server inspection
• PR-based operations are done via comments, not API
• Never expose webhook secrets in output

Common Operations

Project Configuration Review

#!/bin/bash
REPO_DIR="${1:-.}"

echo "=== atlantis.yaml Configuration ==="
cat "${REPO_DIR}/atlantis.yaml" 2>/dev/null || \
cat "${REPO_DIR}/atlantis.yml" 2>/dev/null || \
echo "No atlantis.yaml found -- using server-side config"

echo ""
echo "=== Detected Projects ==="
if [ -f "${REPO_DIR}/atlantis.yaml" ]; then
    cat "${REPO_DIR}/atlantis.yaml" | python3 -c "
import sys, yaml
config = yaml.safe_load(sys.stdin)
for p in config.get('projects', []):
    print(f\"{p.get('name', 'unnamed')}\t{p.get('dir', '.')}\t{p.get('workspace', 'default')}\t{p.get('terraform_version', 'default')}\")
" 2>/dev/null | column -t
else
    find "$REPO_DIR" -name "*.tf" -not -path "*/.terraform/*" -exec dirname {} \; 2>/dev/null | sort -u | head -15
fi

Lock Management

#!/bin/bash
echo "=== Current Locks ==="
atlantis_api GET "locks" | jq -r '
    .[] | "\(.repo_full_name)\t\(.workspace)\tPR#\(.pull.num)\t\(.pull.author)\t\(.time)"
' | column -t

echo ""
echo "=== Stale Locks (>24h) ==="
atlantis_api GET "locks" | jq -r '
    .[] |
    select((.time | fromdateiso8601) < (now - 86400)) |
    "STALE: \(.repo_full_name) workspace=\(.workspace) PR#\(.pull.num) locked_by=\(.pull.author)"
'

echo ""
LOCK_ID="${1:-}"
if [ -n "$LOCK_ID" ]; then
    echo "To unlock, comment 'atlantis unlock' on the PR, or:"
    echo "curl -X DELETE ${ATLANTIS_URL}/api/locks/${LOCK_ID} -H 'X-Atlantis-Token: \$ATLANTIS_TOKEN'"
fi

Workspace Management

#!/bin/bash
echo "=== Workspaces in Use ==="
atlantis_api GET "locks" | jq -r '
    [.[] | .workspace] | unique | .[]
'

echo ""
echo "=== PR Comment Commands ==="
echo "Plan specific workspace:  atlantis plan -w staging"
echo "Apply specific workspace: atlantis apply -w staging"
echo "Plan specific directory:  atlantis plan -d infrastructure/vpc"
echo "Plan all projects:        atlantis plan"

Workflow Configuration

#!/bin/bash
echo "=== Custom Workflows ==="
cat atlantis.yaml 2>/dev/null | python3 -c "
import sys, yaml
config = yaml.safe_load(sys.stdin)
workflows = config.get('workflows', {})
for name, wf in workflows.items():
    print(f'Workflow: {name}')
    plan_steps = wf.get('plan', {}).get('steps', ['init', 'plan'])
    apply_steps = wf.get('apply', {}).get('steps', ['apply'])
    print(f'  Plan steps:  {[s if isinstance(s, str) else list(s.keys())[0] for s in plan_steps]}')
    print(f'  Apply steps: {[s if isinstance(s, str) else list(s.keys())[0] for s in apply_steps]}')
" 2>/dev/null || echo "No custom workflows defined"

echo ""
echo "=== Server-Side Repo Config ==="
echo "Check server repos.yaml for server-side workflow overrides"

Plan/Apply Status

#!/bin/bash
echo "=== Recent PR Activity ==="
atlantis_api GET "jobs" 2>/dev/null | jq '
    .[0:10][] | {
        pr: .pull_num,
        project: .project,
        workspace: .workspace,
        status: .status,
        started: .started_at
    }
' | head -40

echo ""
echo "=== Common PR Commands ==="
echo "atlantis plan                    # Plan all projects"
echo "atlantis plan -w prod            # Plan specific workspace"
echo "atlantis plan -d infra/vpc       # Plan specific directory"
echo "atlantis plan -- -target=aws_s3  # Plan with extra args"
echo "atlantis apply                   # Apply all planned projects"
echo "atlantis unlock                  # Release all locks"

Safety Rules

• NEVER force-unlock without checking if an apply is in progress -- can corrupt state
• Review plan output before commenting atlantis apply on PRs
• Use allowed_overrides carefully -- allows PR authors to bypass server-side configs
• Webhook secrets must be strong -- weak secrets allow unauthorized plan/apply triggers
• Apply requirements (mergeable, approved) should be enforced for production workspaces

Output Format

Present results as a structured report:

Managing Atlantis Report
════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Lock conflicts: Only one PR can lock a workspace/directory at a time -- close stale PRs to release locks
• Webhook delivery failures: GitHub/GitLab webhook timeouts cause missed plan triggers -- check delivery logs
• Terraform version mismatch: Server default version may differ from project needs -- set per-project in atlantis.yaml
• Parallel plan limits: Too many concurrent plans can exhaust server resources -- configure max parallelism
• Auto-merge on apply: If enabled, PRs merge immediately after apply -- ensure branch protection rules are set
• Repo allowlist: Atlantis only processes repos in the allowlist -- new repos must be added
• Custom workflow errors: Script failures in custom workflows may not surface clearly in PR comments
• Credentials in logs: Plan output may contain sensitive values -- ensure Atlantis redacts or use log sanitization