Skip to content

Latest commit

 

History

History
204 lines (159 loc) · 6.18 KB

api-endpoints.md

File metadata and controls

204 lines (159 loc) · 6.18 KB
Raw

API Endpoints

Aside from interacting via pull request comments, Atlantis could respond to a limited number of API endpoints.

Main Endpoints

The API endpoints in this section are disabled by default, since these API endpoints could change the infrastructure directly. To enable the API endpoints, api-secret should be configured.

:::tip Prerequisites

  • Set api-secret as part of the Server Configuration
  • Pass X-Atlantis-Token with the same secret in the request header :::

POST /api/plan

Description

Execute atlantis plan on the specified repository.

Parameters

Name Type Required Description
Repository string Yes Name of the Terraform repository
Ref string Yes Git reference, like a branch name
Type string Yes Type of the VCS provider (Github/Gitlab)
Paths Path Yes Paths to the projects to run the plan
PR int No Pull Request number

Path

Similar to the Options of atlantis plan. Path specifies which directory/workspace within the repository to run the plan. At least one of Directory or Workspace should be specified.

Name Type Required Description
Directory string No Which directory to run plan in relative to root of repo
Workspace string No Terraform workspace of the plan. Use default if Terraform workspaces are unused.

Sample Request

curl --request POST 'https://<ATLANTIS_HOST_NAME>/api/plan' \
--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
}'

Sample Response

{
  "Error": null,
  "Failure": "",
  "ProjectResults": [
    {
      "Command": 1,
      "RepoRelDir": ".",
      "Workspace": "default",
      "Error": null,
      "Failure": "",
      "PlanSuccess": {
        "TerraformOutput": "<redacted>",
        "LockURL": "<redacted>",
        "RePlanCmd": "atlantis plan -d .",
        "ApplyCmd": "atlantis apply -d .",
        "HasDiverged": false
      },
      "PolicyCheckSuccess": null,
      "ApplySuccess": "",
      "VersionSuccess": "",
      "ProjectName": ""
    }
  ],
  "PlansDeleted": false
}

POST /api/apply

Description

Execute atlantis apply on the specified repository.

Parameters

Name Type Required Description
Repository string Yes Name of the Terraform repository
Ref string Yes Git reference, like a branch name
Type string Yes Type of the VCS provider (Github/Gitlab)
Paths Path Yes Paths to the projects to run the apply
PR int No Pull Request number

Path

Similar to the Options of atlantis apply. Path specifies which directory/workspace within the repository to run the apply. At least one of Directory or Workspace should be specified.

Name Type Required Description
Directory string No Which directory to run apply in relative to root of repo
Workspace string No Terraform workspace of the plan. Use default if Terraform workspaces are unused.

Sample Request

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
}'

Sample Response

{
  "Error": null,
  "Failure": "",
  "ProjectResults": [
    {
      "Command": 0,
      "RepoRelDir": ".",
      "Workspace": "default",
      "Error": null,
      "Failure": "",
      "PlanSuccess": null,
      "PolicyCheckSuccess": null,
      "ApplySuccess": "<redacted>",
      "VersionSuccess": "",
      "ProjectName": ""
    }
  ],
  "PlansDeleted": false
}

Other Endpoints

The endpoints listed in this section are non-destructive and therefore don't require authentication nor special secret token.

GET /status

Description

Return the status of the Atlantis server.

Sample Request

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

Sample Response

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

GET /healthz

Description

Serves as the health-check endpoint for a containerized Atlantis server.

Sample Request

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

Sample Response

{
  "status": "ok"
}