Atlantis Integration

Integrate the Cora CLI into your Atlantis workflow to automatically visualize infrastructure changes. Upload state after every apply to keep diagrams current.

Overview

Atlantis is a popular open-source tool for Terraform pull request automation. The Cora CLI integrates with Atlantis custom workflows to provide two key capabilities:

• State visualization - Upload Terraform state after every apply to keep your infrastructure diagrams current.
• Workspace hygiene - Use consistent workspace names so diagrams stay organized across projects and environments.

Prerequisites

• A Cora account with access to API tokens.
• An Atlantis server (version 0.19.0 or later recommended).
• The Cora CLI installed on your Atlantis server.

Step 1: Create an API Token

Visit Settings → API Tokens to create a new token. Copy the token value - you will only see it once.

Tokens are scoped to your organization. Any state uploaded with this token will be associated with your organization in Cora.

Step 2: Install the Cora CLI

Download and install the Cora CLI on your Atlantis server. The CLI is a single static binary with no dependencies.

Download the latest Linux release from the Cora CLI releases page and add it to your PATH. For detailed installation instructions, see the CLI repository README.

Docker-based Atlantis

For Docker-based deployments, add the CLI to your custom Atlantis image. See the CLI repository for the latest download URL.

Step 3: Configure the Token

Add the API token as an environment variable in your Atlantis configuration. The CLI will automatically use the CORA_TOKEN environment variable.

Using environment variables

# In your Atlantis server configuration
export CORA_TOKEN="your-api-token-here"

Using Kubernetes secrets

# Secret
apiVersion: v1
kind: Secret
metadata:
name: cora-credentials
type: Opaque
stringData:
token: "your-api-token-here"

# In your Atlantis deployment
env:
- name: CORA_TOKEN
  valueFrom:
    secretKeyRef:
      name: cora-credentials
      key: token

Step 4: Configure Custom Workflows

Atlantis supports custom workflows that let you run custom commands during apply. You can define these in your repo-level atlantis.yaml or in the server-side repos.yaml config.

State Visualization (Post-Apply Upload)

Upload Terraform state after every successful apply to keep your infrastructure diagrams current. Use the cora upload command as a post-apply step.

Basic workflow (atlantis.yaml)

version: 3
projects:
- name: my-app
  dir: .
  workspace: prod
  workflow: cora

workflows:
cora:
  apply:
    steps:
      - apply
      - run: terraform state pull | cora upload --workspace ${WORKSPACE}

Dynamic workspace names

Use Atlantis environment variables to create meaningful workspace names:

workflows:
cora:
  apply:
    steps:
      - apply
      # Combines project name and workspace, e.g., "networking-prod"
      - run: terraform state pull | cora upload --workspace "${PROJECT_NAME}-${WORKSPACE}"

Multiple projects (monorepo)

For monorepos with multiple Terraform projects:

version: 3
projects:
- name: networking
  dir: terraform/networking
  workflow: cora
- name: application
  dir: terraform/application
  workflow: cora
- name: monitoring
  dir: terraform/monitoring
  workflow: cora

workflows:
cora:
  apply:
    steps:
      - apply
      - run: terraform state pull | cora upload --workspace ${PROJECT_NAME}

Server-Side Repo Config

For organization-wide configuration, define workflows in your Atlantis server's repos.yaml file. This applies the workflow to all repositories without requiring per-repo configuration.

# repos.yaml (server-side config)
repos:
- id: /.*/
  workflow: cora
  allowed_overrides: [workflow]
  allow_custom_workflows: true

workflows:
cora:
  apply:
    steps:
      - apply
      - run: terraform state pull | cora upload --workspace "${PROJECT_NAME:-default}-${WORKSPACE}"

The allowed_overrides setting lets individual repos choose different workflows if needed.

Post-Workflow Hooks

Alternatively, use Atlantis post-workflow hooks to run Cora commands after all projects have been processed:

repos:
- id: /.*/
  post_workflow_hooks:
    - run: |
        if [ "${COMMAND_NAME}" = "apply" ]; then
          terraform state pull | cora upload --workspace "${PROJECT_NAME:-default}"
        fi

Environment Variables Reference

These Atlantis environment variables are available in custom workflow steps and can be used with Cora commands:

Advanced Examples

Terragrunt integration

If you use Terragrunt with Atlantis, adapt the Cora commands accordingly:

workflows:
terragrunt-cora:
  apply:
    steps:
      - env:
          name: TERRAGRUNT_TFPATH
          command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
      - run: terragrunt apply
      - run: terragrunt show -json | cora upload --workspace ${PROJECT_NAME}

Conditional uploads

Only upload to Cora for specific workspaces or conditions:

workflows:
cora-prod-only:
  apply:
    steps:
      - apply
      - run: |
          if [ "${WORKSPACE}" = "prod" ] || [ "${WORKSPACE}" = "production" ]; then
            terraform state pull | cora upload --workspace "${PROJECT_NAME}-${WORKSPACE}"
          fi

Error handling

Continue the workflow even if Cora upload fails (non-blocking):

workflows:
cora-non-blocking:
  apply:
    steps:
      - apply
      - run: terraform state pull | cora upload --workspace ${WORKSPACE} || true

Step 5: Verify the Integration

1. Open a pull request with a Terraform change.
2. Comment atlantis apply to apply changes.
3. After apply succeeds, check the Atlantis logs for Cora upload output.
4. Visit Cora to see your updated infrastructure diagram.

Troubleshooting

"No API token provided"

Make sure the CORA_TOKEN environment variable is set and accessible to the Atlantis process.

"Authentication failed"

Your token may be expired or revoked. Create a new token at Settings → API Tokens.

"Command not found: cora"

Ensure the Cora CLI is installed and available in the PATH of the Atlantis process. You can verify by running which cora or adding a test step to your workflow.

Upload succeeds but diagram is empty

Verify that the Terraform state contains resources. You can check with terraform state list. Empty states (with no resources) will not generate a diagram.

Related Documentation

• Atlantis Custom Workflows - Official Atlantis documentation on custom workflows
• Atlantis Server-Side Repo Config - Configure workflows at the server level
• API Tokens - Manage your API tokens
• Cora CLI Repository - Full CLI documentation and source code