Atlantis

https://www.runatlantis.io/docs
Admin
Atlantis is an open-source CI/CD tool that automatically comments on pull requests with Terraform...
Tokens:73,404
Snippets:914
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Atlantis Server for GitHub App Setup

Source: https://www.runatlantis.io/docs/access-credentials

Use these flags to start the Atlantis server initially to facilitate the GitHub App creation process.

```bash
atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST
```

```bash
atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST --gh-org your-github-org
```

--------------------------------

### Project Configuration Example

Source: https://www.runatlantis.io/docs/repo-level-atlantis-yaml

A comprehensive example of a project definition within the Atlantis configuration, including requirements and workflow settings.

```yaml
name: myname
branch: /mybranch/
dir: mydir
workspace: myworkspace
execution_order_group: 0
delete_source_branch_on_merge: false
repo_locking: true # deprecated: use repo_locks instead
repo_locks:
   mode: on_plan
custom_policy_check: false
autoplan:
terraform_version: 0.11.0
plan_requirements: ["approved"]
apply_requirements: ["approved"]
import_requirements: ["approved"]
silence_pr_comments: ["apply"]
workflow: myworkflow
```

--------------------------------

### GET /status Response

Source: https://www.runatlantis.io/docs/api-endpoints

Example response showing server status information.

```json
{
  "shutting_down": false,
  "in_progress_operations": 0,
  "version": "0.22.3"
}
```

--------------------------------

### atlantis plan usage examples

Source: https://www.runatlantis.io/docs/using-atlantis.html

Examples of running plan for modified projects, specific directories, projects, or workspaces.

```bash
# Runs plan for any projects that Atlantis thinks were modified.
# If an `atlantis.yaml` file is specified, runs plan on the projects that
# were modified as determined by the `when_modified` config.
atlantis plan

# Runs plan in the root directory of the repo with workspace `default`.
atlantis plan -d .

# Runs plan in the `project1` directory of the repo with workspace `default`
atlantis plan -p project1

# Runs plan in the root directory of the repo with workspace `staging`
atlantis plan -w staging
```

--------------------------------

### Configure server with team allowlist

Source: https://www.runatlantis.io/docs/policy-checking

Example of starting the Atlantis server with the --gh-team-allowlist flag to include the policy_check command.

```bash
atlantis server --gh-team-allowlist="*:plan,*:policy_check,*:unlock,myteam:apply"
```

--------------------------------

### Install Atlantis via Helm

Source: https://www.runatlantis.io/docs/deployment

Commands to install the Atlantis Helm chart.

```sh
helm install atlantis runatlantis/atlantis -f values.yaml
```

```sh
helm install -f values.yaml runatlantis/atlantis
```

--------------------------------

### Stage Configuration Example

Source: https://www.runatlantis.io/docs/custom-workflows

Demonstrates how to define steps within a stage, including custom commands and extra arguments.

```yaml
steps:
- run: custom-command
- init
- plan:
    extra_args: [-lock=false]
```

--------------------------------

### Start Atlantis Server for GitHub

Source: https://www.runatlantis.io/docs/deployment

Command to launch the Atlantis server configured for GitHub integration.

```bash
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"
```

--------------------------------

### Write a basic Rego policy

Source: https://www.runatlantis.io/docs/policy-checking

A simple Rego policy example that fails for plans containing newly created null_resources.

```rego
package main

resource_types = {"null_resource"}
```

--------------------------------

### Define projects in atlantis.yaml

Source: https://www.runatlantis.io/docs/custom-workflows

Example configuration for defining multiple projects with distinct names, directories, and workflows.

```yaml
version: 3
projects:
# If two or more projects have the same dir and workspace, they must also have
# a 'name' key to differentiate them.
- name: project1-staging
  dir: project1
  workflow: staging
- name: project1-production
  dir: project1
  workflow: production

workflows:
  # If you didn't define the workflows in your server-side repos.yaml config,
  # you would define them here instead.
```

--------------------------------

### Project Directory Structure

Source: https://www.runatlantis.io/docs/custom-workflows

Example directory structure for a project containing multiple .tfvars files.

```text
.
└── project1
    ├── main.tf
    ├── production.tfvars
    └── staging.tfvars
```

--------------------------------

### Example Directory Structure

Source: https://www.runatlantis.io/docs/autoplanning

A sample file system layout used to demonstrate how Atlantis determines which directories to run terraform plan in.

```text
.
├── modules
│   └── module1
│       └── main.tf
└── project1
    ├── main.tf
    └── modules
        └── module1
            └── main.tf
```

--------------------------------

### Define projects in a consolidated atlantis.yaml

Source: https://www.runatlantis.io/docs/upgrading-atlantis-yaml.html

Example structure for a root-level configuration file managing multiple projects.

```yaml
version: 2
projects:
- dir: project1
  terraform_version: my-version
  workflow: project1-workflow
- dir: project2
  terraform_version: my-version
  workflow: project2-workflow
workflows:
  project1-workflow:
    ...
  project2-workflow:
    ...
```

--------------------------------

### Start Atlantis with Manual GitHub App Configuration

Source: https://www.runatlantis.io/docs/access-credentials

Use these flags when manually creating and configuring the GitHub App for Atlantis.

```bash
atlantis server --gh-app-id <your id> --gh-installation-id <installation id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST
```

--------------------------------

### Configure GitHub Credentials

Source: https://www.runatlantis.io/docs/deployment

Example configuration block for GitHub credentials in values.yaml.

```yaml
github:
  user: foo
  token: bar
  secret: baz
```

--------------------------------

### atlantis state rm examples

Source: https://www.runatlantis.io/docs/using-atlantis.html

Various ways to run state rm across different directories, projects, and workspaces.

```bash
# Runs state rm
atlantis state rm ADDRESS1 ADDRESS2

# Runs state rm in the root directory of the repo with workspace `default`
atlantis state -d . rm ADDRESS

# Runs state rm in the `project1` directory of the repo with workspace `default`
atlantis state -p project1 rm ADDRESS

# Runs state rm in the root directory of the repo with workspace `staging`
atlantis state -w staging rm ADDRESS
```

--------------------------------

### Examples of atlantis import

Source: https://www.runatlantis.io/docs/using-atlantis.html

Various ways to run the import command, including targeting specific directories or projects.

```bash
# Runs import
atlantis import ADDRESS ID

# Runs import in the root directory of the repo with workspace `default`
atlantis import -d . ADDRESS ID

# Runs import in the `project1` directory of the repo with workspace `default`
atlantis import -p project1 ADDRESS ID
```

--------------------------------

### Terragrunt directory structure

Source: https://www.runatlantis.io/docs/custom-workflows

Example directory structure for a project using Terragrunt.

```plain
.
└── live
 	├── prod
 	│	└── terragrunt.hcl
 	└── staging
 	    └── terragrunt.hcl
```

--------------------------------

### Response Auto-Apply Success

Source: https://www.runatlantis.io/docs/api-endpoints

Example of a successful response after an auto-apply action.

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "repository": "owner/repo",
    "ref": "main",
    "action": "apply",
    "status": "success",
    "started_at": "2025-01-21T10:30:00Z",
    "completed_at": "2025-01-21T10:32:00Z",
    "projects": [
      {
        "project_name": "vpc",
        "directory": "modules/vpc",
        "workspace": "production",
        "status": "success",
        "plan_output": "Terraform will perform the following actions:\n  # aws_vpc.main will be updated...",
        "apply_output": "Apply complete! Resources: 0 added, 1 changed, 0 destroyed.",
        "drift_before": {
          "to_add": 0,
          "to_change": 1,
          "to_destroy": 0,
          "to_import": 0,
          "to_forget": 0,
          "total_changes": 1,
          "summary": "Plan: 0 to add, 1 to change, 0 to destroy.",
          "changes_outside": false
        },
        "drift_after": {
          "to_add": 0,
          "to_change": 0,
          "to_destroy": 0,
          "to_import": 0,
          "to_forget": 0,
          "total_changes": 0,
          "summary": "Apply completed successfully",
          "changes_outside": false
        }
      }
    ],
    "summary": {
      "total_projects": 1,
      "success_count": 1,
      "failure_count": 0
    }
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2025-01-21T10:32:00Z"
}
```

--------------------------------

### GitHub App Setup URLs

Source: https://www.runatlantis.io/docs/server-configuration

URLs used to initiate the GitHub App creation process and exchange the authorization code.

```shell
$(hostname)/github-app/setup
```

```shell
$(hostname)/github-app/exchange-code?code=some-code
```

--------------------------------

### Define workflow structure

Source: https://www.runatlantis.io/docs/upgrading-atlantis-yaml.html

Examples of defining and referencing custom workflows in the configuration.

```yaml
version: 2
projects:
- dir: .
  workflow: myworkflow
```

```yaml
version: 2
projects:
...

workflows:
  myworkflow:
  ...
```

```yaml
...
workflows:
  myworkflow:
    plan:
      steps:
      ...
    apply:
      steps:
      ...
```

```yaml
...
workflows:
  myworkflow:
    plan:
      steps:
      ...
```

--------------------------------

### GET /readyz Request

Source: https://www.runatlantis.io/docs/api-endpoints

A curl command to check the readiness of the Atlantis server.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/readyz'
```

--------------------------------

### Start Atlantis Server for GitLab

Source: https://www.runatlantis.io/docs/deployment

Command to launch the Atlantis server configured for GitLab integration.

```bash
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"
```

--------------------------------

### GET /readyz

Source: https://www.runatlantis.io/docs/api-endpoints

The readiness endpoint checks if the server is prepared to handle requests, including verifying connectivity to external dependencies like Redis.

```APIDOC
## GET /readyz

### Description
Readiness endpoint. Returns 200 if the server is ready to handle requests, including connectivity to external dependencies (e.g. Redis). Returns 503 if any dependency is unreachable. Suitable for Kubernetes readiness probes.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- **status** (string) - Indicates the server is healthy.

#### Error Response (503)
- **status** (string) - Indicates the server is unhealthy.
- **error** (string) - Description of the dependency failure.
```

--------------------------------

### .tfvars Files Structure

Source: https://www.runatlantis.io/docs/requirements

Example of a repository structure utilizing multiple .tfvars files.

```plain
.
├── production.tfvars
│── staging.tfvars
└── main.tf
```

--------------------------------

### Build and Run Custom Docker Image

Source: https://www.runatlantis.io/docs/deployment

Commands to build the custom Docker image and start the Atlantis server with GitHub credentials.

```bash
docker build -t {YOUR_DOCKER_ORG}/atlantis-custom .
```

```bash
docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN
```

--------------------------------

### Configure custom workflow with --all-namespaces

Source: https://www.runatlantis.io/docs/policy-checking

Example of a server-side repository configuration using a custom workflow to pass extra arguments to Conftest.

```yaml
repos:
  - id: github.com/myorg/example-repo
    workflow: custom
policies:
  owners:
    users:
      - example-dev
  policy_sets:
    - name: example-conf-tests
      path: /home/atlantis/conftest_policies  # Consider separate vcs & mount into container
      source: local
workflows:
  custom:
    plan:
      steps:
        - init
        - plan
    policy_check:
      steps:
        - policy_check:
            extra_args: ["-p /home/atlantis/conftest_policies/", "--all-namespaces"]
```

--------------------------------

### Response Success

Source: https://www.runatlantis.io/docs/api-endpoints

Example of a successful response containing project status and drift details.

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "repository": "owner/repo",
    "ref": "main",
    "action": "plan",
    "status": "success",
    "started_at": "2025-01-21T10:30:00Z",
    "completed_at": "2025-01-21T10:31:00Z",
    "projects": [
      {
        "project_name": "vpc",
        "directory": "modules/vpc",
        "workspace": "production",
        "status": "success",
        "plan_output": "Terraform will perform the following actions:\n  # aws_vpc.main will be updated...",
        "drift_before": {
          "to_add": 0,
          "to_change": 1,
          "to_destroy": 0,
          "to_import": 0,
          "to_forget": 0,
          "total_changes": 1,
          "summary": "Plan: 0 to add, 1 to change, 0 to destroy.",
          "changes_outside": false
        },
        "drift_after": {
          "to_add": 0,
          "to_change": 1,
          "to_destroy": 0,
          "to_import": 0,
          "to_forget": 0,
          "total_changes": 1,
          "summary": "Plan: 0 to add, 1 to change, 0 to destroy.",
          "changes_outside": false
        }
      },
      {
        "project_name": "ec2",
        "directory": "modules/ec2",
        "workspace": "production",
        "status": "success",
        "plan_output": "No changes. Infrastructure is up-to-date."
      }
    ],
    "summary": {
      "total_projects": 2,
      "success_count": 2,
      "failure_count": 0
    }
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-21T10:30:00Z"
}
```

--------------------------------

### Configure --bitbucket-base-url

Source: https://www.runatlantis.io/docs/server-configuration

Sets the base URL for Bitbucket Server installations. Do not set this for Bitbucket Cloud.

```bash
atlantis server --bitbucket-base-url="http://bitbucket.corp:7990/basepath"
# or
ATLANTIS_BITBUCKET_BASE_URL="http://bitbucket.corp:7990/basepath"
```

--------------------------------

### Configure --gitlab-hostname

Source: https://www.runatlantis.io/docs/server-configuration

Sets the hostname for GitLab Enterprise installations. Defaults to gitlab.com.

```bash
atlantis server --gitlab-hostname="my.gitlab.enterprise.com"
# or
ATLANTIS_GITLAB_HOSTNAME="my.gitlab.enterprise.com"
```

--------------------------------

### atlantis import for_each example

Source: https://www.runatlantis.io/docs/using-atlantis.html

When importing for_each resources, a single quoted address is required.

```bash
atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0
```

--------------------------------

### Configure --gitea-base-url

Source: https://www.runatlantis.io/docs/server-configuration

Sets the base URL for the Gitea installation. Must include the protocol and defaults to https://gitea.com.

```bash
atlantis server --gitea-base-url="http://your-gitea.corp:7990/basepath"
# or
ATLANTIS_GITEA_BASE_URL="http://your-gitea.corp:7990/basepath"
```

--------------------------------

### Define custom workflows in atlantis.yaml

Source: https://www.runatlantis.io/docs/server-side-repo-config

Example of defining custom plan and apply steps within a repository's atlantis.yaml file.

```yaml
# atlantis.yaml
version: 3
projects:
- dir: .
  workflow: custom1
workflows:
  custom1:
    plan:
      steps:
      - init
      - run: my custom plan command
    apply:
      steps:
      - run: my custom apply command
```

--------------------------------

### Automatic Environment Variable Files structure

Source: https://www.runatlantis.io/docs/using-atlantis.html

Example directory structure for automatic inclusion of workspace-specific variable files.

```plain
my-terraform-project/
├── main.tf
├── variables.tf
└── env/
    ├── default.tfvars
    ├── staging.tfvars
    └── production.tfvars
```

--------------------------------

### Define Repository Configuration Rules

Source: https://www.runatlantis.io/docs/server-side-repo-config

Example of defining multiple repository matching rules where specific repository configurations override general ones.

```yaml
repos:
- id: /.*/
  allow_custom_workflows: true
  apply_requirements: [approved]
- id: github.com/owner/repo
  apply_requirements: []
```

--------------------------------

### Start Atlantis Server for GitHub Enterprise

Source: https://www.runatlantis.io/docs/deployment

Command to launch the Atlantis server configured for GitHub Enterprise, requiring the hostname.

```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io or tenant.ghe.com
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--gh-hostname="$HOSTNAME" \
--repo-allowlist="$REPO_ALLOWLIST"
```

--------------------------------

### Configure planning triggers

Source: https://www.runatlantis.io/docs/repo-level-atlantis-yaml

Example of defining custom file patterns that trigger a plan for a project, relative to the project directory.

```plain
.
├── modules
│   └── module1
│       ├── main.tf
│       ├── outputs.tf
│       └── submodule
│           ├── main.tf
│           └── outputs.tf
└── project1
    └── main.tf
```

```yaml
version: 3
projects:
   - dir: project1
     autoplan:
        when_modified: ["../modules/**/*.tf", "*.tf*", ".terraform.lock.hcl"]
```

--------------------------------

### Configure --gh-team-allowlist for Policy Checking

Source: https://www.runatlantis.io/docs/server-configuration

Example of allowlisting the policy_check command alongside plan and apply permissions.

```bash
atlantis server --gh-team-allowlist="*:plan,*:policy_check,myteam:apply"
```

--------------------------------

### Define Custom Workflows for .tfvars Files

Source: https://www.runatlantis.io/docs/custom-workflows

Example configuration for staging and production workflows using specific .tfvars files.

```yaml
# repos.yaml or atlantis.yaml
workflows:
  staging:
    plan:
      steps:
      - init
      - plan:
          extra_args: ["-var-file", "staging.tfvars"]
    # NOTE: no need to define the apply stage because it will default
    # to the normal apply stage.

  production:
    plan:
      steps:
      - init
      - plan:
          extra_args: ["-var-file", "production.tfvars"]
    apply:
      steps:
        - apply:
            extra_args: ["-var-file", "production.tfvars"]
    import:
      steps:
        - init
        - import:
            extra_args: ["-var-file", "production.tfvars"]
    state_rm:
      steps:
        - init
        - state_rm:
            extra_args: ["-lock=false"]
```

--------------------------------

### GET /api/drift/status Response with drift

Source: https://www.runatlantis.io/docs/api-endpoints

Example response indicating drift detected in projects.

```json
{
  "success": true,
  "data": {
    "repository": "owner/repo",
    "projects": [
      {
        "project_name": "vpc",
        "directory": "modules/vpc",
        "workspace": "production",
        "ref": "main",
        "has_drift": true,
        "drift": {
          "to_add": 2,
          "to_change": 1,
          "to_destroy": 0,
          "to_import": 0,
          "to_forget": 0,
          "total_changes": 3,
          "summary": "Plan: 2 to add, 1 to change, 0 to destroy.",
          "changes_outside": false
        },
        "last_checked": "2025-01-21T10:30:00Z"
      },
      {
        "project_name": "ec2",
        "directory": "modules/ec2",
        "workspace": "production",
        "ref": "main",
        "has_drift": false,
        "last_checked": "2025-01-21T10:25:00Z"
      }
    ],
    "checked_at": "2025-01-21T10:30:00Z",
    "summary": {
      "total_projects": 2,
      "projects_with_drift": 1,
      "projects_without_drift": 1,
      "projects_with_errors": 0
    }
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-21T10:30:00Z"
}
```

--------------------------------

### GET /api/locks Response (No Locks)

Source: https://www.runatlantis.io/docs/api-endpoints

Example response when no project locks are currently held.

```json
{
  "Locks": []
}
```

--------------------------------

### Atlantis Configuration with All Keys

Source: https://www.runatlantis.io/docs/repo-level-atlantis-yaml

A comprehensive example of an atlantis.yaml file demonstrating all available configuration keys, including project settings, workflow definitions, and global options.

```yaml
version: 3 # Available since v0.1.0
automerge: true # Available since v0.15.0
autodiscover: # Available since v0.18.0
  mode: auto
  ignore_paths:
  - some/path
delete_source_branch_on_merge: true # Available since v0.15.0
parallel_plan: true # Available since v0.17.0
parallel_apply: true # Available since v0.17.0
abort_on_execution_order_fail: true # Available since v0.17.0
projects:
- name: my-project-name # Available since v0.1.0
  branch: /main/ # Available since v0.21.0
  dir: . # Available since v0.1.0
  workspace: default # Available since v0.1.0
  terraform_distribution: terraform # Available since v0.33.0
  terraform_version: v0.11.0 # Available since v0.1.0
  delete_source_branch_on_merge: true # Available since v0.17.0
  repo_locking: true # deprecated: use repo_locks instead, Available since v0.17.0
  repo_locks: # Available since v0.17.0
    mode: on_plan
  custom_policy_check: false # Available since v0.17.0
  autoplan: # Available since v0.1.0
    when_modified: ["*.tf", "../modules/**/*.tf", ".terraform.lock.hcl"]
    enabled: true
  plan_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  apply_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  import_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  silence_pr_comments: ["apply"] # Available since v0.17.0
  execution_order_group: 1 # Available since v0.17.0
  depends_on: # Available since v0.20.0
    - project-1
  workflow: myworkflow # Available since v0.17.0
workflows: # Available since v0.1.0
  myworkflow:
    plan:
      steps:
      - run: my-custom-command arg1 arg2
      - run:
          command: my-custom-command arg1 arg2
          output: hide
      - init
      - plan:
          extra_args: ["-lock", "false"]
      - run: my-custom-command arg1 arg2
    apply:
      steps:
      - run: echo hi
      - apply
allowed_regexp_prefixes: # Available since v0.19.0
- dev/
- staging/
```

--------------------------------

### Override show command with SHOWFILE

Source: https://www.runatlantis.io/docs/custom-workflows

Example of using the SHOWFILE environment variable to override the built-in show command.

```bash
run: terraform show -json $PLANFILE > $SHOWFILE
```

--------------------------------

### Define Environment-Specific Atlantis Configurations

Source: https://www.runatlantis.io/docs/server-side-repo-config

Example configurations for production and staging environments using version 3 schema.

```yaml
# atlantis-production.yaml
version: 3
projects:
- name: project
  branch: /production/
  dir: infrastructure/production
---
# atlantis-staging.yaml
version: 3
projects:
  - name: project
    branch: /staging/
    dir: infrastructure/staging
```

--------------------------------

### Define policy configuration in server-side repo

Source: https://www.runatlantis.io/docs/policy-checking

Example of defining a policy set with owners and local paths in the server-side repository configuration.

```yaml
policies:
  owners:
    users:
      - nishkrishnan
  policy_sets:
    - name: deny_null_resource
      path: <CODE_DIRECTORY>/policies/deny_null_resource/
      source: local
    - name: deny_local_exec
      path: <CODE_DIRECTORY>/policies/deny_local_exec/
      source: local
      approve_count: 2
      owners:
        users:
          - pseudomorph
```

--------------------------------

### Sample Response for /readyz

Source: https://www.runatlantis.io/docs/api-endpoints

A successful response indicating the server is ready.

```json
{
  "status": "ok"
}
```

--------------------------------

### GET /api/locks Response

Source: https://www.runatlantis.io/docs/api-endpoints

Example response showing a list of active project locks.

```json
{
  "Locks": [
    {
      "Name": "owner/repo/./default/terraform",
      "ProjectName": "terraform",
      "ProjectRepo": "owner/repo",
      "ProjectRepoPath": ".",
      "PullID": "123",
      "PullURL": "https://github.com/owner/repo/pull/123",
      "User": "jdoe",
      "Workspace": "default",
      "Time": "2025-02-13T16:47:42.040856-08:00"
    }
  ]
}
```

--------------------------------

### GET /api/drift/status Response (no drift data)

Source: https://www.runatlantis.io/docs/api-endpoints

Example response when no drift data is available for the repository.

```json
{
  "success": true,
  "data": {
    "repository": "owner/repo",
    "projects": [],
    "checked_at": "2025-01-21T10:30:00Z",
    "summary": {
      "total_projects": 0,
      "projects_with_drift": 0,
      "projects_without_drift": 0,
      "projects_with_errors": 0
    }
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2025-01-21T10:30:00Z"
}
```

--------------------------------

### DRYing up Projects with YAML Anchors

Source: https://www.runatlantis.io/docs/repo-level-atlantis-yaml

An example showing how to use YAML anchors and aliases to reduce duplication when defining multiple projects with similar configurations.

```yaml
projects:
   - &template
     name: template
     dir: template
     workflow: custom
     autoplan:
        enabled: true
        when_modified:
           - "./terraform/modules/**/*.tf"
           - "**/*.tf"
           - ".terraform.lock.hcl"

   - <<: *template
     name: ue1-prod-titan
     dir: ./terraform/titan
     workspace: ue1-prod

   - <<: *template
     name: ue1-stage-titan
     dir: ./terraform/titan
     workspace: ue1-stage

   - <<: *template
     name: ue1-dev-titan
     dir: ./terraform/titan
     workspace: ue1-dev
```

--------------------------------

### GET /api/drift/remediate/ Request

Source: https://www.runatlantis.io/docs/api-endpoints

Example cURL request to retrieve a remediation result. Requires the X-Atlantis-Token header for authentication.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/api/drift/remediate/550e8400-e29b-41d4-a716-446655440000?repository=owner/repo&type=Github' \
--header 'X-Atlantis-Token: <ATLANTIS_API_SECRET>'
```

--------------------------------

### Define custom workflows in server-side config

Source: https://www.runatlantis.io/docs/server-configuration

Example JSON structure for defining custom workflows and steps within the server-side repository configuration.

```json
{
   "repos": [],
   "workflows": {
      "custom": {
         "plan": {
            "steps": [
               "init",
               {
                  "plan": {
                     "extra_args": ["extra", "args"]
                  }
               },
               {
                  "run": "my custom command"
               }
            ]
         }
      }
   }
}
```

--------------------------------

### GET /status

Source: https://www.runatlantis.io/docs/api-endpoints

Return the status of the Atlantis server.

```APIDOC
## GET /status

### Description
Return the status of the Atlantis server.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **shutting_down** (boolean) - Server shutdown status
- **in_progress_operations** (integer) - Number of operations currently in progress
- **version** (string) - Atlantis server version
```

--------------------------------

### Consolidate project directory structure

Source: https://www.runatlantis.io/docs/upgrading-atlantis-yaml.html

Shows the transition from multiple per-directory configuration files to a single root configuration.

```plain
.
├── project1
│   └── atlantis.yaml
└── project2
    └── atlantis.yaml
```

```plain
.
├── atlantis.yaml
├── project1
└── project2
```

--------------------------------

### GET /api/locks

Source: https://www.runatlantis.io/docs/api-endpoints

List the currently held project locks.

```APIDOC
## GET /api/locks

### Description
List the currently held project locks.

### Method
GET

### Endpoint
/api/locks

### Response
#### Success Response (200)
- **Locks** (array) - List of currently held project locks.
```

--------------------------------

### GET /status Request

Source: https://www.runatlantis.io/docs/api-endpoints

Retrieves the current status of the Atlantis server.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/status'
```

--------------------------------

### GET /api/locks Request

Source: https://www.runatlantis.io/docs/api-endpoints

Retrieves the currently held project locks.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/api/locks'
```

--------------------------------

### Configure --ssl-key-file

Source: https://www.runatlantis.io/docs/server-configuration

Specifies the file containing the x509 private key matching the SSL certificate.

```bash
atlantis server --ssl-key-file="/etc/ssl/private/my-cert.key"
# or
ATLANTIS_SSL_KEY_FILE="/etc/ssl/private/my-cert.key"
```

--------------------------------

### GET /api/drift/status

Source: https://www.runatlantis.io/docs/using-atlantis.html

Retrieves the cached results of the most recent drift detection.

```APIDOC
## GET /api/drift/status

### Description
View cached drift results.

### Method
GET

### Endpoint
/api/drift/status
```

--------------------------------

### Response Partial Failure

Source: https://www.runatlantis.io/docs/api-endpoints

Example of a response where some projects succeeded while others failed.

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "repository": "owner/repo",
    "ref": "main",
    "action": "plan",
    "status": "partial",
    "started_at": "2025-01-21T10:30:00Z",
    "completed_at": "2025-01-21T10:31:00Z",
    "projects": [
      {
        "project_name": "vpc",
        "directory": "modules/vpc",
        "workspace": "production",
        "status": "success",
        "plan_output": "No changes. Infrastructure is up-to-date."
      },
      {
        "project_name": "ec2",
        "directory": "modules/ec2",
        "workspace": "production",
        "status": "failed",
        "error": "terraform plan failed: Error acquiring state lock"
      }
    ],
    "summary": {
      "total_projects": 2,
      "success_count": 1,
      "failure_count": 1
    }
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440002",
  "timestamp": "2025-01-21T10:31:00Z"
}
```

--------------------------------

### Patch Atlantis Manifests

Source: https://www.runatlantis.io/docs/deployment

Example of a strategic merge patch for the Atlantis StatefulSet.

```yaml
patchesStrategicMerge:
- |-
  apiVersion: apps/v1
  kind: StatefulSet
  metadata:
    name: atlantis
  spec:
    template:
      spec:
        ...
```

--------------------------------

### Configure --write-git-creds

Source: https://www.runatlantis.io/docs/server-configuration

Write out a .git-credentials file with the provider user and token to allow cloning private modules over HTTPS or SSH.

```bash
atlantis server --write-git-creds
# or
ATLANTIS_WRITE_GIT_CREDS=true
```

--------------------------------

### Migrate pre/post commands to workflow steps

Source: https://www.runatlantis.io/docs/upgrading-atlantis-yaml.html

Demonstrates replacing legacy pre/post hooks with explicit run steps in a workflow.

```yaml
pre_init:
  commands:
  - "curl http://example.com"
# pre_get commands are run when the Terraform version is < 0.9.0
pre_get:
  commands:
  - "curl http://example.com"
pre_plan:
  commands:
  - "curl http://example.com"
post_plan:
  commands:
  - "curl http://example.com"
pre_apply:
  commands:
  - "curl http://example.com"
post_apply:
  commands:
  - "curl http://example.com"
```

```yaml
...
workflows:
  myworkflow:
    plan:
      steps:
      - run: curl http://example.com
      - init
      - plan
      - run: curl http://example.com
    apply:
      steps:
      - run: curl http://example.com
      - apply
      - run: curl http://example.com
```

--------------------------------

### GET /healthz Request

Source: https://www.runatlantis.io/docs/api-endpoints

Liveness endpoint to check if the Atlantis process is running.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/healthz'
```

--------------------------------

### Configure --config

Source: https://www.runatlantis.io/docs/server-configuration

Specifies the path to the Atlantis configuration file.

```bash
atlantis server --config="my/config/file.yaml"
```

--------------------------------

### Dockerfile for CDKTF

Source: https://www.runatlantis.io/docs/custom-workflows

A custom Dockerfile based on the Atlantis image with npm and cdktf-cli installed.

```dockerfile
# Dockerfile
FROM ghcr.io/runatlantis/atlantis:v0.19.7

USER root
RUN apk add npm && npm i -g cdktf-cli
```

--------------------------------

### Enable --web-basic-auth

Source: https://www.runatlantis.io/docs/server-configuration

Enables basic authentication for the Atlantis web server.

```bash
atlantis server --web-basic-auth
```

--------------------------------

### Configure --repo-config

Source: https://www.runatlantis.io/docs/server-configuration

Sets the path to a YAML server-side repository configuration file.

```bash
atlantis server --repo-config="path/to/repos.yaml"
# or
ATLANTIS_REPO_CONFIG="path/to/repos.yaml"
```

--------------------------------

### GET /api/drift/remediate successful response

Source: https://www.runatlantis.io/docs/api-endpoints

The JSON structure returned when remediation results are found.

```json
{
  "success": true,
  "data": {
    "repository": "owner/repo",
    "count": 2,
    "results": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "repository": "owner/repo",
        "ref": "main",
        "action": "plan",
        "status": "success",
        "started_at": "2025-01-21T10:30:00Z",
        "completed_at": "2025-01-21T10:31:00Z",
        "projects": [],
        "summary": {
          "total_projects": 2,
          "success_count": 2,
          "failure_count": 0
        }
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "repository": "owner/repo",
        "ref": "main",
        "action": "apply",
        "status": "partial",
        "started_at": "2025-01-21T09:00:00Z",
        "completed_at": "2025-01-21T09:05:00Z",
        "projects": [],
        "summary": {
          "total_projects": 3,
          "success_count": 2,
          "failure_count": 1
        }
      }
    ]
  },
  "error": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-21T10:30:00Z"
}
```

--------------------------------

### Configure --repo-config-json

Source: https://www.runatlantis.io/docs/server-configuration

Provides the server-side repository configuration directly as a JSON string.

```bash
atlantis server --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}'
```

--------------------------------

### Track only FAIL lines with regex

Source: https://www.runatlantis.io/docs/policy-checking

Use the (?m) flag to track only lines starting with FAIL.

```yaml
policy_item_regex: "(?m)^FAIL.*"
```

--------------------------------

### POST /api/apply Success Response

Source: https://www.runatlantis.io/docs/api-endpoints

Example JSON response indicating a successful apply operation.

```json
{
  "Error": null,
  "Failure": "",
  "ProjectResults": [
    {
      "Error": null,
      "Failure": "",
      "ApplySuccess": "Apply complete! Resources: 2 added, 1 changed, 0 destroyed.",
      "RepoRelDir": ".",
      "Workspace": "default",
      "ProjectName": ""
    }
  ],
  "PlansDeleted": false
}
```

--------------------------------

### Configure --enable-diff-markdown-format

Source: https://www.runatlantis.io/docs/server-configuration

Enable diff markdown format.

```bash
atlantis server --enable-diff-markdown-format
```

--------------------------------

### Configure --autoplan-file-list

Source: https://www.runatlantis.io/docs/server-configuration

Defines a list of file patterns that trigger project planning. Use single quotes to avoid shell expansion of wildcards.

```bash
# NOTE: Use single quotes to avoid shell expansion of *.
atlantis server --autoplan-file-list='**/*.tf,project1/*.pkr.hcl'
# or
ATLANTIS_AUTOPLAN_FILE_LIST='**/*.tf,project1/*.pkr.hcl'
```

--------------------------------

### Rego Policy for Resource Creation

Source: https://www.runatlantis.io/docs/policy-checking

Example Rego policy that denies the creation of null_resource types.

```rego
# all resources
resources[resource_type] = all {
    some resource_type
    resource_types[resource_type]
    all := [name |
        name:= input.resource_changes[_]
        name.type == resource_type
    ]
}

# number of creations of resources of a given type
num_creates[resource_type] = num {
    some resource_type
    resource_types[resource_type]
    all := resources[resource_type]
    creates := [res |  res:= all[_]; res.change.actions[_] == "create"]
    num := count(creates)
}

deny[msg] {
    num_resources := num_creates["null_resource"]

    num_resources > 0

    msg := "null resources cannot be created"
}
```

--------------------------------

### Define a custom workflow step

Source: https://www.runatlantis.io/docs/upgrading-atlantis-yaml.html

Example of a custom run step within an atlantis.yaml workflow.

```yaml
# atlantis.yaml
workflows:
  custom:
    plan:
      steps:
      - run: my custom command
```

--------------------------------

### Start Atlantis with GitHub App Credentials

Source: https://www.runatlantis.io/docs/access-credentials

Restart the Atlantis server using the generated GitHub App ID, key file, and webhook secret.

```bash
atlantis server --gh-app-id <your id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST
```

--------------------------------

### Apply Command Restriction

Source: https://www.runatlantis.io/docs/automerging

Example of an apply command that will be blocked if other plans in the pull request have failed.

```shell
atlantis apply -d dir1
```

--------------------------------

### GET /api/drift/status Request with filters

Source: https://www.runatlantis.io/docs/api-endpoints

Retrieves drift status with additional query parameters for filtering.

```shell
curl --request GET 'https://<ATLANTIS_HOST_NAME>/api/drift/status?repository=owner/repo&type=Github&project=vpc&path=modules/vpc&workspace=production&ref=main&base_branch=main' \
  --header 'X-Atlantis-Token: <API_TOKEN>'
```

--------------------------------

### Enable parallel plans and applies

Source: https://www.runatlantis.io/docs/repo-level-atlantis-yaml

Global configuration to enable parallel execution for plans and applies across projects.

```yaml
version: 3
parallel_plan: true
parallel_apply: true
```

--------------------------------

### Configure --log-level

Source: https://www.runatlantis.io/docs/server-configuration

Sets the logging level for the server. Defaults to info.

```bash
atlantis server --log-level="<debug|info|warn|error>"
# or
ATLANTIS_LOG_LEVEL="<debug|info|warn|error>"
```

--------------------------------

### Error API Response

Source: https://www.runatlantis.io/docs/api-endpoints

The JSON response returned when a request, authentication, or setup error occurs.

```json
{
  "error": "request \"{}\" is missing fields"
}
```

--------------------------------

### Configure --tfe-hostname

Source: https://www.runatlantis.io/docs/server-configuration

Specifies the hostname for a private Terraform Enterprise installation. Defaults to app.terraform.io if not set.

```bash
atlantis server --tfe-hostname="my-terraform-enterprise.company.com"
# or
ATLANTIS_TFE_HOSTNAME="my-terraform-enterprise.company.com"
```

--------------------------------

### Configure --autoplan-modules

Source: https://www.runatlantis.io/docs/server-configuration

Enables autoplanning for changes to modules.

```bash
atlantis server --autoplan-modules
```

--------------------------------

### Enable Basic Authentication

Source: https://www.runatlantis.io/docs/server-configuration

Enable Basic Authentication on the Atlantis web service.

```bash
# or
ATLANTIS_WEB_BASIC_AUTH=true
```

--------------------------------

### POST /api/drift/detect Request

Source: https://www.runatlantis.io/docs/api-endpoints

Example cURL request to trigger drift detection for specific projects in a repository.

```shell
curl --request POST 'https://<ATLANTIS_HOST_NAME>/api/drift/detect' \
--header 'X-Atlantis-Token: <ATLANTIS_API_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "repository": "owner/repo",
    "ref": "main",
    "type": "Github",
    "projects": ["vpc", "ec2"],
    "include_plan_output": true
}'
```

--------------------------------

### POST /api/apply Request

Source: https://www.runatlantis.io/docs/api-endpoints

Example cURL request to execute an Atlantis apply operation on a specified repository.

```shell
curl --request POST 'https://<ATLANTIS_HOST_NAME>/api/apply' \
--header 'X-Atlantis-Token: <ATLANTIS_API_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Repository": "repo-name",
    "Ref": "main",
    "Type": "Github",
    "Paths": [{
      "Directory": ".",
      "Workspace": "default"
    }],
    "PR": 2
}'
```

--------------------------------

### Configure --gh-app-key

Source: https://www.runatlantis.io/docs/server-configuration

Sets the private key for the GitHub App.

```bash
atlantis server --gh-app-key="-----BEGIN RSA PRIVATE KEY-----(...)"
```
Tokens:
Raw