public/atlantis
1
0
Fork 0
mirror of https://git.vectorsigma.ru/public/atlantis.git synced 2026-07-28 21:38:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): add markdownlint and apply rules (#4557)

Browse Source
This commit is contained in:
Christian Winther
2024-05-14 22:30:14 +02:00
committed by GitHub
parent ee103c3688
commit 6fe0303279
42 changed files with 1060 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.editorconfig Normal file
View File

@@ -0,0 +1,12 @@
root = true
[*]
charset = utf-8
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
[*.md]
indent_style = space
indent_size = 3
trim_trailing_whitespace = false

6
.github/workflows/website.yml vendored
View File

@@ -48,6 +48,12 @@ jobs:
steps: steps:
- uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4 - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4
- name: markdown-lint
uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8 # v16
with:
config: .markdownlint.yaml
globs: 'runatlantis.io/**/*.md'
- uses: wyvox/action-setup-pnpm@6597ef5c1300fe08efa6bc75e6141f7153e2b4cc # v3 - uses: wyvox/action-setup-pnpm@6597ef5c1300fe08efa6bc75e6141f7153e2b4cc # v3
with: with:
node-version: 20 node-version: 20

33
.markdownlint.yaml Normal file
View File

@@ -0,0 +1,33 @@
# MD013/line-length
#
# We're not particular about line length, generally preferring longer
# lines, since tools like Grammarly and other writing assistance tools
# work best with "normal" lines not broken up arbitrary.
#
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
MD013: false
# MD033/no-inline-html
#
# We're fine with inline HTML, there are lots of valid VitePress features
# that depends on this.
#
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
MD033: false
# MD024/no-duplicate-heading
#
# VitePress do not follow GitHub heading styling, so duplicate headlines
# are fine as long as they are not siblings (aka same indention hierarchy)
#
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md
MD024:
siblings_only: true
# MD051/link-fragments
#
# VitePress generate these differently that markdownlint expects, so disabling
# for now, and something to improve on later (cc @jippi)
#
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md
MD051: false

5
package.json
View File

@@ -8,10 +8,13 @@
"sass": "^1.77.0", "sass": "^1.77.0",
"sitemap-ts": "^1.6.1", "sitemap-ts": "^1.6.1",
"vitepress": "^1.1.4", "vitepress": "^1.1.4",
"vue": "^3.4.27" "vue": "^3.4.27",
"markdownlint-cli": "^0.40.0"
}, },
"scripts": { "scripts": {
"website:dev": "vitepress dev --host localhost --port 8080 runatlantis.io", "website:dev": "vitepress dev --host localhost --port 8080 runatlantis.io",
"website:lint": "markdownlint runatlantis.io",
"website:lint-fix": "markdownlint --fix runatlantis.io",
"website:build": "vitepress build runatlantis.io", "website:build": "vitepress build runatlantis.io",
"e2e": "playwright test" "e2e": "playwright test"
} }

5
runatlantis.io/contributing.md
View File

@@ -1,3 +1,6 @@
---
aside: false
---
# Atlantis Contributing Documentation # Atlantis Contributing Documentation
These docs are for users who want to contribute to the Atlantis project. This These docs are for users who want to contribute to the Atlantis project. This
@@ -9,6 +12,6 @@ If you're new, check out the [Guide](./guide.md) or the
[Documentation](./docs.md). [Documentation](./docs.md).
::: :::
### Next Steps ## Next Steps
- [Events Controller](./contributing/events-controller.md)  –  How do the events work? - [Events Controller](./contributing/events-controller.md)  –  How do the events work?

1
runatlantis.io/contributing/events-controller.md
View File

@@ -51,6 +51,7 @@ documentation.
- [GitHub Pull Request](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request) - [GitHub Pull Request](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request)
- [GitLab Merge Request](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events) - [GitLab Merge Request](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events)
- [Gitea Webhooks](https://docs.gitea.com/next/usage/webhooks) - [Gitea Webhooks](https://docs.gitea.com/next/usage/webhooks)
</details> </details>
The following list shows the supported events: The following list shows the supported events:

5
runatlantis.io/docs.md
View File

@@ -1,3 +1,6 @@
---
aside: false
---
# Atlantis Documentation # Atlantis Documentation
These docs are for users that are ready to get Atlantis installed and start using it. These docs are for users that are ready to get Atlantis installed and start using it.
@@ -7,7 +10,7 @@ If you're new here, check out the [Guide](./guide.md)
where you can try our [Test Drive](./guide/test-drive.md) or [Run Atlantis Locally](./guide/testing-locally.md). where you can try our [Test Drive](./guide/test-drive.md) or [Run Atlantis Locally](./guide/testing-locally.md).
::: :::
### Next Steps ## Next Steps
* [Installing Atlantis](./docs/installation-guide.md)&nbsp;&nbsp;–&nbsp;&nbsp;Get Atlantis up and running * [Installing Atlantis](./docs/installation-guide.md)&nbsp;&nbsp;–&nbsp;&nbsp;Get Atlantis up and running
* [Configuring Atlantis](./docs/configuring-atlantis.md)&nbsp;&nbsp;–&nbsp;&nbsp;Configure how Atlantis works for your specific use-cases * [Configuring Atlantis](./docs/configuring-atlantis.md)&nbsp;&nbsp;–&nbsp;&nbsp;Configure how Atlantis works for your specific use-cases

115
runatlantis.io/docs/access-credentials.md
View File

@@ -1,9 +1,11 @@
# Git Host Access Credentials # Git Host Access Credentials
This page describes how to create credentials for your Git host (GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps) This page describes how to create credentials for your Git host (GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps)
that Atlantis will use to make API calls. that Atlantis will use to make API calls.
## Create an Atlantis user (optional) ## Create an Atlantis user (optional)
We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user. We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user.
This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes
@@ -13,8 +15,10 @@ will come from that user so it might be confusing if its coming from a personal
<p align="center"><i>An example comment coming from the @atlantisbot user</i></p> <p align="center"><i>An example comment coming from the @atlantisbot user</i></p>
## Generating an Access Token ## Generating an Access Token
Once you've created a new user (or decided to use an existing one), you need to Once you've created a new user (or decided to use an existing one), you need to
generate an access token. Read on for the instructions for your specific Git host: generate an access token. Read on for the instructions for your specific Git host:
* [GitHub](#github-user) * [GitHub](#github-user)
* [GitHub app](#github-app) * [GitHub app](#github-app)
* [GitLab](#gitlab) * [GitLab](#gitlab)
@@ -24,9 +28,10 @@ generate an access token. Read on for the instructions for your specific Git hos
* [Azure DevOps](#azure-devops) * [Azure DevOps](#azure-devops)
### GitHub user ### GitHub user
- Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
- Create the token with **repo** scope * Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
- Record the access token * Create the token with **repo** scope
* Record the access token
::: warning ::: warning
Your Atlantis user must also have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses: Your Atlantis user must also have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses:
![Atlantis status](./images/status.png) ![Atlantis status](./images/status.png)
@@ -35,16 +40,16 @@ Your Atlantis user must also have "Write permissions" (for repos in an organizat
### GitHub app ### GitHub app
#### Create the GitHub App Using Atlantis #### Create the GitHub App Using Atlantis
::: warning ::: warning
Available in Atlantis versions **newer** than 0.13.0. Available in Atlantis versions **newer** than 0.13.0.
::: :::
* Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command.
- Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command. * Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis
- Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis * A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link.
- A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link. * Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` * Restart Atlantis with new flags: `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`.
- Restart Atlantis with new flags: `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`.
NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file). NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file).
@@ -58,11 +63,11 @@ GitHub App handles the webhook calls by itself, hence there is no need to create
#### Manually Creating the GitHub app #### Manually Creating the GitHub app
- Create the GitHub app as an Administrator * Create the GitHub app as an Administrator
- Ensure the app is registered / installed with the organization / user * Ensure the app is registered / installed with the organization / user
- See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) * See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)
- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` * Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
- Start Atlantis with the following flags: `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`. * Start Atlantis with the following flags: `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`.
NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file). NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file).
@@ -92,56 +97,62 @@ Since v0.19.7, a new permission for `Administration` has been added. If you have
Since v0.22.3, a new permission for `Members` has been added, which is required for features that apply permissions to an organizations team members rather than individual users. Like the `Administration` permission above, updating Atlantis will not automatically add this permission, so if you wish to use features that rely on checking team membership you will need to add this manually. Since v0.22.3, a new permission for `Members` has been added, which is required for features that apply permissions to an organizations team members rather than individual users. Like the `Administration` permission above, updating Atlantis will not automatically add this permission, so if you wish to use features that rely on checking team membership you will need to add this manually.
::: :::
| Type | Access | | Type | Access |
| --------------- | ------------------- | | --------------- | ------------------- |
| Administration | Read-only | | Administration | Read-only |
| Checks | Read and write | | Checks | Read and write |
| Commit statuses | Read and write | | Commit statuses | Read and write |
| Contents | Read and write | | Contents | Read and write |
| Issues | Read and write | | Issues | Read and write |
| Metadata | Read-only (default) | | Metadata | Read-only (default) |
| Pull requests | Read and write | | Pull requests | Read and write |
| Webhooks | Read and write | | Webhooks | Read and write |
| Members | Read-only | | Members | Read-only |
### GitLab ### GitLab
- Follow: [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token)
- Create a token with **api** scope * Follow: [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token)
- Record the access token * Create a token with **api** scope
* Record the access token
### Gitea ### Gitea
- Go to "Profile and Settings" > "Settings" in Gitea (top-right)
- Go to "Applications" under "User Settings" in Gitea * Go to "Profile and Settings" > "Settings" in Gitea (top-right)
- Create a token under the "Manage Access Tokens" with the following permissions: * Go to "Applications" under "User Settings" in Gitea
- issue: Read and Write * Create a token under the "Manage Access Tokens" with the following permissions:
- repository: Read and Write * issue: Read and Write
- user: Read * repository: Read and Write
- Record the access token * user: Read
* Record the access token
### Bitbucket Cloud (bitbucket.org) ### Bitbucket Cloud (bitbucket.org)
- Create an App Password by following [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
- Label the password "atlantis" * Create an App Password by following [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them * Label the password "atlantis"
- Record the access token * Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
* Record the access token
### Bitbucket Server (aka Stash) ### Bitbucket Server (aka Stash)
- Click on your avatar in the top right and select **Manage account**
- Click **Personal access tokens** in the sidebar * Click on your avatar in the top right and select **Manage account**
- Click **Create a token** * Click **Personal access tokens** in the sidebar
- Name the token **atlantis** * Click **Create a token**
- Give the token **Read** Project permissions and **Write** Pull request permissions * Name the token **atlantis**
- Click **Create** and record the access token * Give the token **Read** Project permissions and **Write** Pull request permissions
* Click **Create** and record the access token
NOTE: Atlantis will send the token as a [Bearer Auth to the Bitbucket API](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html#HTTPaccesstokens-UsingHTTPaccesstokens) instead of using Basic Auth. NOTE: Atlantis will send the token as a [Bearer Auth to the Bitbucket API](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html#HTTPaccesstokens-UsingHTTPaccesstokens) instead of using Basic Auth.
### Azure DevOps ### Azure DevOps
- Create a Personal access token by following [Azure DevOps: Use personal access tokens to authenticate](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
- Label the password "atlantis" * Create a Personal access token by following [Azure DevOps: Use personal access tokens to authenticate](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
- The minimum scopes required for this token are: * Label the password "atlantis"
- Code (Read & Write) * The minimum scopes required for this token are:
- Code (Status) * Code (Read & Write)
- Member Entitlement Management (Read) * Code (Status)
- Record the access token * Member Entitlement Management (Read)
* Record the access token
## Next Steps ## Next Steps
Once you've got your user and access token, you're ready to create a webhook secret. See [Creating a Webhook Secret](webhook-secrets.md). Once you've got your user and access token, you're ready to create a webhook secret. See [Creating a Webhook Secret](webhook-secrets.md).

36
runatlantis.io/docs/api-endpoints.md
View File

@@ -21,18 +21,18 @@ Execute [atlantis plan](using-atlantis.md#atlantis-plan) on the specified reposi
#### Parameters #### Parameters
| Name | Type | Required | Description | | Name | Type | Required | Description |
|------------|-----------------------------------|----------|------------------------------------------| |------------|---------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository | | Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name | | Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) | | Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | [ [Path](api-endpoints.md#path) ] | Yes | Paths to the projects to run the plan | | Paths | Path | Yes | Paths to the projects to run the plan |
| PR | int | No | Pull Request number | | PR | int | No | Pull Request number |
##### Path #### Path
Similar to the [Options](using-atlantis.md#options) of `atlantis plan`. Path specifies which directory/workspace Similar to the [Options](using-atlantis.md#options) of `atlantis plan`. Path specifies which directory/workspace
within the repository to run the plan. within the repository to run the plan.
At least one of `Directory` or `Workspace` should be specified. At least one of `Directory` or `Workspace` should be specified.
| Name | Type | Required | Description | | Name | Type | Required | Description |
@@ -96,18 +96,18 @@ Execute [atlantis apply](using-atlantis.md#atlantis-apply) on the specified repo
#### Parameters #### Parameters
| Name | Type | Required | Description | | Name | Type | Required | Description |
|------------|-------------------------------------|----------|------------------------------------------| |------------|--------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository | | Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name | | Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) | | Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | [ [Path](api-endpoints.md#path-1) ] | Yes | Paths to the projects to run the apply | | Paths | Path | Yes | Paths to the projects to run the apply |
| PR | int | No | Pull Request number | | PR | int | No | Pull Request number |
##### Path #### Path
Similar to the [Options](using-atlantis.md#options-1) of `atlantis apply`. Path specifies which directory/workspace Similar to the [Options](using-atlantis.md#options-1) of `atlantis apply`. Path specifies which directory/workspace
within the repository to run the apply. within the repository to run the apply.
At least one of `Directory` or `Workspace` should be specified. At least one of `Directory` or `Workspace` should be specified.
| Name | Type | Required | Description | | Name | Type | Required | Description |

16
runatlantis.io/docs/automerging.md
View File

@@ -1,44 +1,53 @@
# Automerging # Automerging
Atlantis can be configured to automatically merge a pull request after all plans have Atlantis can be configured to automatically merge a pull request after all plans have
been successfully applied. been successfully applied.
![Automerge](./images/automerge.png) ![Automerge](./images/automerge.png)
## How To Enable ## How To Enable
Automerging can be enabled either by: Automerging can be enabled either by:
1. Passing the `--automerge` flag to `atlantis server`. This sets the parameter globally; however, explicit declaration in the repo config will be respected and take priority. 1. Passing the `--automerge` flag to `atlantis server`. This sets the parameter globally; however, explicit declaration in the repo config will be respected and take priority.
1. Setting `automerge: true` in the repo's `atlantis.yaml` file: 1. Setting `automerge: true` in the repo's `atlantis.yaml` file:
```yaml ```yaml
version: 3 version: 3
automerge: true automerge: true
projects: projects:
- dir: . - dir: .
``` ```
:::tip NOTE :::tip NOTE
If a repo has an `atlantis.yaml` file, then each project in the repo needs If a repo has an `atlantis.yaml` file, then each project in the repo needs
to be configured under the `projects` key. to be configured under the `projects` key.
::: :::
## How to Disable ## How to Disable
If automerge is enabled, you can disable it for a single `atlantis apply` If automerge is enabled, you can disable it for a single `atlantis apply`
command with the `--auto-merge-disabled` option. command with the `--auto-merge-disabled` option.
## Requirements ## Requirements
### All Plans Must Succeed ### All Plans Must Succeed
When automerge is enabled, **all plans** in a pull request **must succeed** before When automerge is enabled, **all plans** in a pull request **must succeed** before
**any** plans can be applied. **any** plans can be applied.
For example, imagine this scenario: For example, imagine this scenario:
1. I open a pull request that makes changes to two Terraform projects, in `dir1/` 1. I open a pull request that makes changes to two Terraform projects, in `dir1/`
and `dir2/`. and `dir2/`.
1. The plan for `dir2/` fails because my Terraform syntax is wrong. 1. The plan for `dir2/` fails because my Terraform syntax is wrong.
In this scenario, I can't run In this scenario, I can't run
```
```shell
atlantis apply -d dir1 atlantis apply -d dir1
``` ```
Even though that plan succeeded, because **all** plans must succeed for **any** plans Even though that plan succeeded, because **all** plans must succeed for **any** plans
to be saved. to be saved.
@@ -47,8 +56,9 @@ autoplan. Then I will be able to apply both plans.
### All Plans must be applied ### All Plans must be applied
If multiple projects/dirs/workspaces are configured to be planned automatically, If multiple projects/dirs/workspaces are configured to be planned automatically,
then they should all be applied before Atlantis automatically merges the PR. then they should all be applied before Atlantis automatically merges the PR.
## Permissions ## Permissions
The Atlantis VCS user must have the ability to merge pull requests. The Atlantis VCS user must have the ability to merge pull requests.

16
runatlantis.io/docs/autoplanning.md
View File

@@ -1,8 +1,10 @@
# Autoplanning # Autoplanning
On any **new** pull request or **new commit** to an existing pull request, Atlantis will attempt to On any **new** pull request or **new commit** to an existing pull request, Atlantis will attempt to
run `terraform plan` in the directories it thinks hold modified Terraform projects. run `terraform plan` in the directories it thinks hold modified Terraform projects.
The algorithm it uses is as follows: The algorithm it uses is as follows:
1. Get list of all modified files in pull request 1. Get list of all modified files in pull request
1. Filter to those containing `.tf` 1. Filter to those containing `.tf`
1. Get the directories that those files are in 1. Get the directories that those files are in
@@ -11,8 +13,10 @@ The algorithm it uses is as follows:
contains a `main.tf` run plan in that directory, otherwise ignore the change (see below for exceptions). contains a `main.tf` run plan in that directory, otherwise ignore the change (see below for exceptions).
## Example ## Example
Given the directory structure: Given the directory structure:
```
```plain
. .
├── modules ├── modules
│   └── module1 │   └── module1
@@ -26,21 +30,25 @@ Given the directory structure:
* If `project1/main.tf` were modified, we would run `plan` in `project1` * If `project1/main.tf` were modified, we would run `plan` in `project1`
* If `modules/module1/main.tf` were modified, we would not automatically run `plan` because we couldn't determine the location of the terraform project * If `modules/module1/main.tf` were modified, we would not automatically run `plan` because we couldn't determine the location of the terraform project
* You could use an [atlantis.yaml](repo-level-atlantis-yaml.md#configuring-planning) file to specify which projects to plan when this module changed * You could use an [atlantis.yaml](repo-level-atlantis-yaml.md#configuring-planning) file to specify which projects to plan when this module changed
* You could enable [module autoplanning](server-configuration.md#autoplan-modules) which indexes projects to their local module dependencies. * You could enable [module autoplanning](server-configuration.md#autoplan-modules) which indexes projects to their local module dependencies.
* Or you could manually plan with `atlantis plan -d <dir>` * Or you could manually plan with `atlantis plan -d <dir>`
* If `project1/modules/module1/main.tf` were modified, we would look one level above `project1/modules` * If `project1/modules/module1/main.tf` were modified, we would look one level above `project1/modules`
into `project1/`, see that there was a `main.tf` file and so run plan in `project1/` into `project1/`, see that there was a `main.tf` file and so run plan in `project1/`
## Bitbucket-Specific Notes ## Bitbucket-Specific Notes
Bitbucket does not have a webhook that triggers only upon a new PR or commit. To fix this we cache the last commit to see if it has changed. If the cache is emptied, Atlantis will think your commit is new and you may see extra plans. Bitbucket does not have a webhook that triggers only upon a new PR or commit. To fix this we cache the last commit to see if it has changed. If the cache is emptied, Atlantis will think your commit is new and you may see extra plans.
This scenario can happen if: This scenario can happen if:
* Atlantis restarts * Atlantis restarts
* You are running multiple Atlantis instances behind a load balancer * You are running multiple Atlantis instances behind a load balancer
## Customizing ## Customizing
If you would like to customize how Atlantis determines which directory to run in If you would like to customize how Atlantis determines which directory to run in
or disable it all together you need to create an `atlantis.yaml` file. or disable it all together you need to create an `atlantis.yaml` file.
See See
* [Disabling Autoplanning](repo-level-atlantis-yaml.md#disabling-autoplanning) * [Disabling Autoplanning](repo-level-atlantis-yaml.md#disabling-autoplanning)
* [Configuring Planning](repo-level-atlantis-yaml.md#configuring-planning) * [Configuring Planning](repo-level-atlantis-yaml.md#configuring-planning)

12
runatlantis.io/docs/checkout-strategy.md
View File

@@ -7,6 +7,7 @@ variable that get passed to the `atlantis server` command.
Atlantis supports `branch` and `merge` strategies. Atlantis supports `branch` and `merge` strategies.
## Branch ## Branch
If set to `branch` (the default), Atlantis will check out the source branch If set to `branch` (the default), Atlantis will check out the source branch
of the pull request. of the pull request.
@@ -17,6 +18,7 @@ If the pull request was asking to merge `branch` into `main`,
Atlantis would check out `branch` at commit `C3`. Atlantis would check out `branch` at commit `C3`.
## Merge ## Merge
The problem with the `branch` strategy, is that if users push branches that are The problem with the `branch` strategy, is that if users push branches that are
out of date with `main`, then their `terraform plan` could be deleting out of date with `main`, then their `terraform plan` could be deleting
some resources that were configured in the main branch. some resources that were configured in the main branch.
@@ -49,9 +51,9 @@ commit is pushed to `main` **after** Atlantis runs `plan`, nothing will happen.
To optimize cloning time, Atlantis can perform a shallow clone by specifying the `--checkout-depth` flag. The cloning is performed in a following manner: To optimize cloning time, Atlantis can perform a shallow clone by specifying the `--checkout-depth` flag. The cloning is performed in a following manner:
- Shallow clone of the default branch is performed with depth of `--checkout-depth` value of zero (full clone). * Shallow clone of the default branch is performed with depth of `--checkout-depth` value of zero (full clone).
- `branch` is retrieved, including the same amount of commits. * `branch` is retrieved, including the same amount of commits.
- Merge base of the default branch and `branch` is checked for existence in the shallow clone. * Merge base of the default branch and `branch` is checked for existence in the shallow clone.
- If the merge base is not present, it means that either of the branches are ahead of the merge base by more than `--checkout-depth` commits. In this case full repo history is fetched. * If the merge base is not present, it means that either of the branches are ahead of the merge base by more than `--checkout-depth` commits. In this case full repo history is fetched.
If the commit history often diverges by more than the default checkout depth then the `--checkout-depth` flag should be tuned to avoid full fetches. If the commit history often diverges by more than the default checkout depth then the `--checkout-depth` flag should be tuned to avoid full fetches.

64
runatlantis.io/docs/command-requirements.md
View File

@@ -1,6 +1,7 @@
# Command Requirements # Command Requirements
## Intro ## Intro
Atlantis requires certain conditions be satisfied **before** `atlantis apply` and `atlantis import` Atlantis requires certain conditions be satisfied **before** `atlantis apply` and `atlantis import`
commands can be run: commands can be run:
@@ -9,31 +10,41 @@ commands can be run:
* [UnDiverged](#undiverged) - requires pull requests to be ahead of the base branch * [UnDiverged](#undiverged) - requires pull requests to be ahead of the base branch
## What Happens If The Requirement Is Not Met? ## What Happens If The Requirement Is Not Met?
If the requirement is not met, users will see an error if they try to run `atlantis apply`: If the requirement is not met, users will see an error if they try to run `atlantis apply`:
![Mergeable Apply Requirement](./images/apply-requirement.png) ![Mergeable Apply Requirement](./images/apply-requirement.png)
## Supported Requirements ## Supported Requirements
### Approved ### Approved
The `approved` requirement will prevent applies unless the pull request is approved The `approved` requirement will prevent applies unless the pull request is approved
by at least one person other than the author. by at least one person other than the author.
#### Usage #### Usage
The `approved` requirement by: The `approved` requirement by:
1. Creating a `repos.yaml` file with the `apply_requirements` key: 1. Creating a `repos.yaml` file with the `apply_requirements` key:
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
apply_requirements: [approved] apply_requirements: [approved]
``` ```
1. Or by allowing an `atlantis.yaml` file to specify the `apply_requirements` key in the `repos.yaml` config: 1. Or by allowing an `atlantis.yaml` file to specify the `apply_requirements` key in the `repos.yaml` config:
#### repos.yaml
**repos.yaml**
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
allowed_overrides: [apply_requirements] allowed_overrides: [apply_requirements]
``` ```
#### atlantis.yaml **atlantis.yaml**
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -42,7 +53,9 @@ The `approved` requirement by:
``` ```
#### Meaning #### Meaning
Each VCS provider has different rules around who can approve: Each VCS provider has different rules around who can approve:
* **GitHub** – **Any user with read permissions** to the repo can approve a pull request * **GitHub** – **Any user with read permissions** to the repo can approve a pull request
* **GitLab** – The user who can approve can be set in the [repo settings](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) * **GitLab** – The user who can approve can be set in the [repo settings](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
* **Bitbucket Cloud (bitbucket.org)** – A user can approve their own pull request but * **Bitbucket Cloud (bitbucket.org)** – A user can approve their own pull request but
@@ -56,11 +69,15 @@ To require **certain people** to approve the pull request, look at the
::: :::
### Mergeable ### Mergeable
The `mergeable` requirement will prevent applies unless a pull request is able to be merged. The `mergeable` requirement will prevent applies unless a pull request is able to be merged.
#### Usage #### Usage
Set the `mergeable` requirement by: Set the `mergeable` requirement by:
1. Creating a `repos.yaml` file with the `apply_requirements` key: 1. Creating a `repos.yaml` file with the `apply_requirements` key:
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
@@ -68,14 +85,17 @@ Set the `mergeable` requirement by:
``` ```
1. Or by allowing an `atlantis.yaml` file to specify `plan_requirements`, `apply_requirements` and `import_requirements` keys in the `repos.yaml` config: 1. Or by allowing an `atlantis.yaml` file to specify `plan_requirements`, `apply_requirements` and `import_requirements` keys in the `repos.yaml` config:
#### repos.yaml
**repos.yaml**
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements] allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
``` ```
#### atlantis.yaml **atlantis.yaml**
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -86,6 +106,7 @@ Set the `mergeable` requirement by:
``` ```
#### Meaning #### Meaning
Each VCS provider has a different concept of "mergeability": Each VCS provider has a different concept of "mergeability":
::: warning ::: warning
@@ -95,10 +116,12 @@ See also the `branch` keyword in [Server Side Repo Config](server-side-repo-conf
::: :::
#### GitHub #### GitHub
In GitHub, if you're not using [Protected Branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) then In GitHub, if you're not using [Protected Branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) then
all pull requests are mergeable unless there is a conflict. all pull requests are mergeable unless there is a conflict.
If you set up Protected Branches then you can enforce: If you set up Protected Branches then you can enforce:
* Requiring certain status checks to be passing * Requiring certain status checks to be passing
* Requiring certain people to have reviewed and approved the pull request * Requiring certain people to have reviewed and approved the pull request
* Requiring `CODEOWNERS` to have reviewed and approved the pull request * Requiring `CODEOWNERS` to have reviewed and approved the pull request
@@ -118,6 +141,7 @@ If you set `atlantis/apply` to the mergeable requirement, use the `--gh-allow-me
::: :::
#### GitLab #### GitLab
For GitLab, a merge request will be merged if there are no conflicts, no unresolved discussions if it is a project requirement and if all necessary approvers have approved the pull request. For GitLab, a merge request will be merged if there are no conflicts, no unresolved discussions if it is a project requirement and if all necessary approvers have approved the pull request.
For pipelines, if the project requires that pipelines must succeed, all builds except the apply command status will be checked. For pipelines, if the project requires that pipelines must succeed, all builds except the apply command status will be checked.
@@ -125,6 +149,7 @@ For pipelines, if the project requires that pipelines must succeed, all builds e
For Jobs with allow_failure setting set to true, will be ignored. If the pipeline has been skipped and the project allows merging, it will be marked as mergeable. For Jobs with allow_failure setting set to true, will be ignored. If the pipeline has been skipped and the project allows merging, it will be marked as mergeable.
#### Bitbucket.org (Bitbucket Cloud) and Bitbucket Server (Stash) #### Bitbucket.org (Bitbucket Cloud) and Bitbucket Server (Stash)
For Bitbucket, we just check if there is a conflict that is preventing a For Bitbucket, we just check if there is a conflict that is preventing a
merge. We don't check anything else because Bitbucket's API doesn't support it. merge. We don't check anything else because Bitbucket's API doesn't support it.
@@ -132,9 +157,11 @@ If you need a specific check, please
[open an issue](https://github.com/runatlantis/atlantis/issues/new). [open an issue](https://github.com/runatlantis/atlantis/issues/new).
#### Azure DevOps #### Azure DevOps
In Azure DevOps, all pull requests are mergeable unless there is a conflict. You can set a pull request to "Complete" right away, or set "Auto-Complete", which will merge after all branch policies are met. See [Review code with pull requests](https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-requests?view=azure-devops). In Azure DevOps, all pull requests are mergeable unless there is a conflict. You can set a pull request to "Complete" right away, or set "Auto-Complete", which will merge after all branch policies are met. See [Review code with pull requests](https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-requests?view=azure-devops).
[Branch policies](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) can: [Branch policies](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) can:
* Require a minimum number of reviewers * Require a minimum number of reviewers
* Allow users to approve their own changes * Allow users to approve their own changes
* Allow completion even if some reviewers vote "Waiting" or "Reject" * Allow completion even if some reviewers vote "Waiting" or "Reject"
@@ -146,12 +173,16 @@ At this time, the Azure DevOps client only supports merging using the default 'n
::: :::
### UnDiverged ### UnDiverged
Prevent applies if there are any changes on the base branch since the most recent plan. Prevent applies if there are any changes on the base branch since the most recent plan.
Applies to `merge` checkout strategy only which you need to set via `--checkout-strategy` flag. Applies to `merge` checkout strategy only which you need to set via `--checkout-strategy` flag.
#### Usage #### Usage
You can set the `undiverged` requirement by: You can set the `undiverged` requirement by:
1. Creating a `repos.yaml` file with `plan_requirements`, `apply_requirements` and `import_requirements` keys: 1. Creating a `repos.yaml` file with `plan_requirements`, `apply_requirements` and `import_requirements` keys:
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
@@ -159,15 +190,19 @@ You can set the `undiverged` requirement by:
apply_requirements: [undiverged] apply_requirements: [undiverged]
import_requirements: [undiverged] import_requirements: [undiverged]
``` ```
1. Or by allowing an `atlantis.yaml` file to specify the `plan_requirements`, `apply_requirements` and `import_requirements` keys in your `repos.yaml` config: 1. Or by allowing an `atlantis.yaml` file to specify the `plan_requirements`, `apply_requirements` and `import_requirements` keys in your `repos.yaml` config:
#### repos.yaml
**repos.yaml**
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements] allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
``` ```
#### atlantis.yaml **atlantis.yaml**
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -176,7 +211,9 @@ You can set the `undiverged` requirement by:
apply_requirements: [undiverged] apply_requirements: [undiverged]
import_requirements: [undiverged] import_requirements: [undiverged]
``` ```
#### Meaning #### Meaning
The `merge` checkout strategy creates a temporary merge commit and runs the `plan` on the Atlantis local version of the PR The `merge` checkout strategy creates a temporary merge commit and runs the `plan` on the Atlantis local version of the PR
source and destination branch. The local destination branch can become out of date since changes to the destination branch are not fetched source and destination branch. The local destination branch can become out of date since changes to the destination branch are not fetched
if there are no changes to the source branch. `undiverged` enforces that Atlantis local version of main is up to date if there are no changes to the source branch. `undiverged` enforces that Atlantis local version of main is up to date
@@ -184,16 +221,21 @@ with remote so that the state of the source during the `apply` is identical to t
time. time.
## Setting Command Requirements ## Setting Command Requirements
As mentioned above, you can set command requirements via flags, in `repos.yaml`, or in `atlantis.yaml` if `repos.yaml` As mentioned above, you can set command requirements via flags, in `repos.yaml`, or in `atlantis.yaml` if `repos.yaml`
allows the override. allows the override.
### Flags Override ### Flags Override
Flags **override** any `repos.yaml` or `atlantis.yaml` settings so they are equivalent to always Flags **override** any `repos.yaml` or `atlantis.yaml` settings so they are equivalent to always
having that apply requirement set. having that apply requirement set.
### Project-Specific Settings ### Project-Specific Settings
If you only want some projects/repos to have apply requirements, then you must If you only want some projects/repos to have apply requirements, then you must
1. Specifying which repos have which requirements via the `repos.yaml` file. 1. Specifying which repos have which requirements via the `repos.yaml` file.
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
@@ -220,7 +262,9 @@ If you only want some projects/repos to have apply requirements, then you must
config. config.
For example if I have two directories, `staging` and `production`, I might use: For example if I have two directories, `staging` and `production`, I might use:
#### repos.yaml
**repos.yaml:**
```yaml ```yaml
repos: repos:
- id: /.*/ - id: /.*/
@@ -228,7 +272,8 @@ If you only want some projects/repos to have apply requirements, then you must
# Allow any repo to specify apply_requirements in atlantis.yaml # Allow any repo to specify apply_requirements in atlantis.yaml
``` ```
#### atlantis.yaml **atlantis.yaml:**
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -247,13 +292,16 @@ If you only want some projects/repos to have apply requirements, then you must
``` ```
### Multiple Requirements ### Multiple Requirements
You can set any or all of `approved`, `mergeable`, and `undiverged` requirements. You can set any or all of `approved`, `mergeable`, and `undiverged` requirements.
## Who Can Apply? ## Who Can Apply?
Once the apply requirement is satisfied, **anyone** that can comment on the pull Once the apply requirement is satisfied, **anyone** that can comment on the pull
request can run the actual `atlantis apply` command. request can run the actual `atlantis apply` command.
## Next Steps ## Next Steps
* For more information on GitHub pull request reviews and approvals see: [GitHub: About pull request reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) * For more information on GitHub pull request reviews and approvals see: [GitHub: About pull request reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews)
* For more information on GitLab merge request reviews and approvals (only supported on GitLab Enterprise) see: [GitLab: Merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/). * For more information on GitLab merge request reviews and approvals (only supported on GitLab Enterprise) see: [GitLab: Merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/).
* For more information on Bitbucket pull request reviews and approvals see: [BitBucket: Use pull requests for code review](https://confluence.atlassian.com/bitbucket/pull-requests-and-code-review-223220593.html) * For more information on Bitbucket pull request reviews and approvals see: [BitBucket: Use pull requests for code review](https://confluence.atlassian.com/bitbucket/pull-requests-and-code-review-223220593.html)

4
runatlantis.io/docs/configuring-atlantis.md
View File

@@ -1,11 +1,13 @@
# Configuring Atlantis # Configuring Atlantis
There are three methods for configuring Atlantis: There are three methods for configuring Atlantis:
1. Passing flags to the `atlantis server` command 1. Passing flags to the `atlantis server` command
1. Creating a server-side repo config file and using the `--repo-config` flag 1. Creating a server-side repo config file and using the `--repo-config` flag
1. Placing an `atlantis.yaml` file at the root of your Terraform repositories 1. Placing an `atlantis.yaml` file at the root of your Terraform repositories
## Flags ## Flags
Flags to `atlantis server` are used to configure the global operation of Flags to `atlantis server` are used to configure the global operation of
Atlantis, for example setting credentials for your Git Host Atlantis, for example setting credentials for your Git Host
or configuring SSL certs. or configuring SSL certs.
@@ -13,12 +15,14 @@ or configuring SSL certs.
See [Server Configuration](server-configuration.md) for more details. See [Server Configuration](server-configuration.md) for more details.
## Server-Side Repo Config ## Server-Side Repo Config
A Server-Side Repo Config file is used to control per-repo behaviour A Server-Side Repo Config file is used to control per-repo behaviour
and what users can do in repo-level `atlantis.yaml` files. and what users can do in repo-level `atlantis.yaml` files.
See [Server-Side Repo Config](server-side-repo-config.md) for more details. See [Server-Side Repo Config](server-side-repo-config.md) for more details.
## Repo-Level `atlantis.yaml` Files ## Repo-Level `atlantis.yaml` Files
`atlantis.yaml` files placed at the root of your Terraform repos can be used to `atlantis.yaml` files placed at the root of your Terraform repos can be used to
change the default Atlantis behaviour for each repo. change the default Atlantis behaviour for each repo.

200
runatlantis.io/docs/configuring-webhooks.md
View File

@@ -1,7 +1,9 @@
# Configuring Webhooks # Configuring Webhooks
Atlantis needs to receive Webhooks from your Git host so that it can respond to pull request events. Atlantis needs to receive Webhooks from your Git host so that it can respond to pull request events.
:::tip Prerequisites :::tip Prerequisites
* You have created an [access credential](access-credentials.md) * You have created an [access credential](access-credentials.md)
* You have created a [webhook secret](webhook-secrets.md) * You have created a [webhook secret](webhook-secrets.md)
* You have [deployed](deployment.md) Atlantis and have a url for it * You have [deployed](deployment.md) Atlantis and have a url for it
@@ -10,6 +12,7 @@ Atlantis needs to receive Webhooks from your Git host so that it can respond to
See the instructions for your specific provider below. See the instructions for your specific provider below.
## GitHub/GitHub Enterprise ## GitHub/GitHub Enterprise
You can install your webhook at the [organization](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts) level, or for each individual repository. You can install your webhook at the [organization](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts) level, or for each individual repository.
::: tip NOTE ::: tip NOTE
@@ -21,121 +24,130 @@ When authenticating as a GitHub App, Webhooks are automatically created and need
If you're installing on the organization, navigate to your organization's page and click **Settings**. If you're installing on the organization, navigate to your organization's page and click **Settings**.
If installing on a single repository, navigate to the repository home page and click **Settings**. If installing on a single repository, navigate to the repository home page and click **Settings**.
- Select **Webhooks** or **Hooks** in the sidebar
- Click **Add webhook** * Select **Webhooks** or **Hooks** in the sidebar
- set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** * Click **Add webhook**
- double-check you added `/events` to the end of your URL. * set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- set **Content type** to `application/json` * double-check you added `/events` to the end of your URL.
- set **Secret** to the Webhook Secret you generated previously * set **Content type** to `application/json`
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. * set **Secret** to the Webhook Secret you generated previously
- select **Let me select individual events** * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- check the boxes * select **Let me select individual events**
- **Pull request reviews** * check the boxes
- **Pushes** * **Pull request reviews**
- **Issue comments** * **Pushes**
- **Pull requests** * **Issue comments**
- leave **Active** checked * **Pull requests**
- click **Add webhook** * leave **Active** checked
- See [Next Steps](#next-steps) * click **Add webhook**
* See [Next Steps](#next-steps)
## GitLab ## GitLab
If you're using GitLab, navigate to your project's home page in GitLab If you're using GitLab, navigate to your project's home page in GitLab
- Click **Settings > Webhooks** in the sidebar
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** * Click **Settings > Webhooks** in the sidebar
- double-check you added `/events` to the end of your URL. * set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- set **Secret Token** to the Webhook Secret you generated previously * double-check you added `/events` to the end of your URL.
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. * set **Secret Token** to the Webhook Secret you generated previously
- check the boxes * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- **Push events** * check the boxes
- **Comments** * **Push events**
- **Merge Request events** * **Comments**
- leave **Enable SSL verification** checked * **Merge Request events**
- click **Add webhook** * leave **Enable SSL verification** checked
- See [Next Steps](#next-steps) * click **Add webhook**
* See [Next Steps](#next-steps)
## Gitea ## Gitea
If you're using Gitea, navigate to your project's home page in Gitea If you're using Gitea, navigate to your project's home page in Gitea
- Click **Settings > Webhooks** in the top- and then sidebar
- Click **Add webhook > Gitea** (Gitea webhooks are service specific, but this works) * Click **Settings > Webhooks** in the top- and then sidebar
- set **Target URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** * Click **Add webhook > Gitea** (Gitea webhooks are service specific, but this works)
- double-check you added `/events` to the end of your URL. * set **Target URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- set **Secret** to the Webhook Secret you generated previously * double-check you added `/events` to the end of your URL.
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. * set **Secret** to the Webhook Secret you generated previously
- Select **Custom Events...** * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Check the boxes * Select **Custom Events...**
- **Repository events > Push** * Check the boxes
- **Issue events > Issue Comment** * **Repository events > Push**
- **Pull Request events > Pull Request** * **Issue events > Issue Comment**
- **Pull Request events > Pull Request Comment** * **Pull Request events > Pull Request**
- **Pull Request events > Pull Request Reviewed** * **Pull Request events > Pull Request Comment**
- **Pull Request events > Pull Request Synchronized** * **Pull Request events > Pull Request Reviewed**
- Leave **Active** checked * **Pull Request events > Pull Request Synchronized**
- Click **Add Webhook** * Leave **Active** checked
- See [Next Steps](#next-steps) * Click **Add Webhook**
* See [Next Steps](#next-steps)
## Bitbucket Cloud (bitbucket.org) ## Bitbucket Cloud (bitbucket.org)
- Go to your repo's home page
- Click **Settings** in the sidebar * Go to your repo's home page
- Click **Webhooks** under the **WORKFLOW** section * Click **Settings** in the sidebar
- Click **Add webhook** * Click **Webhooks** under the **WORKFLOW** section
- Enter "Atlantis" for **Title** * Click **Add webhook**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** * Enter "Atlantis" for **Title**
- double-check you added `/events` to the end of your URL. * set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- Keep **Status** as Active * double-check you added `/events` to the end of your URL.
- Don't check **Skip certificate validation** because NGROK has a valid cert. * Keep **Status** as Active
- Select **Choose from a full list of triggers** * Don't check **Skip certificate validation** because NGROK has a valid cert.
- Under **Repository** **un**check everything * Select **Choose from a full list of triggers**
- Under **Issues** leave everything **un**checked * Under **Repository** **un**check everything
- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created * Under **Issues** leave everything **un**checked
- Click **Save** * Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created
* Click **Save**
<img src="../guide/images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px"> <img src="../guide/images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px">
- See [Next Steps](#next-steps) * See [Next Steps](#next-steps)
## Bitbucket Server (aka Stash) ## Bitbucket Server (aka Stash)
- Go to your repo's home page
- Click **Settings** in the sidebar * Go to your repo's home page
- Click **Webhooks** under the **WORKFLOW** section * Click **Settings** in the sidebar
- Click **Create webhook** * Click **Webhooks** under the **WORKFLOW** section
- Enter "Atlantis" for **Name** * Click **Create webhook**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** * Enter "Atlantis" for **Name**
- Double-check you added `/events` to the end of your URL. * set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- Set **Secret** to the Webhook Secret you generated previously * Double-check you added `/events` to the end of your URL.
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. * Set **Secret** to the Webhook Secret you generated previously
- Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 600px;"> * Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added
- See [Next Steps](#next-steps) * Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 600px;">
* See [Next Steps](#next-steps)
## Azure DevOps ## Azure DevOps
Webhooks are installed at the [team project](https://docs.microsoft.com/en-us/azure/devops/organizations/projects/about-projects?view=azure-devops) level, but may be restricted to only fire based on events pertaining to [specific repos](https://docs.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops) within the team project. Webhooks are installed at the [team project](https://docs.microsoft.com/en-us/azure/devops/organizations/projects/about-projects?view=azure-devops) level, but may be restricted to only fire based on events pertaining to [specific repos](https://docs.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops) within the team project.
- Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName` * Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName`
- Select **Project settings** in the lower-left corner * Select **Project settings** in the lower-left corner
- Select **Service hooks** * Select **Service hooks**
- If you see the message "You do not have sufficient permissions to view or configure subscriptions." you need to ensure your user is a member of either the organization's "Project Collection Administrators" group or the project's "Project Administrators" group. * If you see the message "You do not have sufficient permissions to view or configure subscriptions." you need to ensure your user is a member of either the organization's "Project Collection Administrators" group or the project's "Project Administrators" group.
- To add your user to the Project Collection Build Administrators group, navigate to the organization level, click **Organization Settings** and then click **Permissions**. You should be at `https://dev.azure.com/<organization>/_settings/groups`. Now click on the **\<organization\>/Project Collection Administrators** group and add your user as a member. * To add your user to the Project Collection Build Administrators group, navigate to the organization level, click **Organization Settings** and then click **Permissions**. You should be at `https://dev.azure.com/<organization>/_settings/groups`. Now click on the **\<organization\>/Project Collection Administrators** group and add your user as a member.
- To add your user to the Project Administrators group, navigate to the project level, click **Project Settings** and then click **Permissions**. You should be at `https://dev.azure.com/<organization>/<project>/_settings/permissions`. Now click on the **\<project\>/Project Administrators** group and add your user as a member. * To add your user to the Project Administrators group, navigate to the project level, click **Project Settings** and then click **Permissions**. You should be at `https://dev.azure.com/<organization>/<project>/_settings/permissions`. Now click on the **\<project\>/Project Administrators** group and add your user as a member.
- Click **Create subscription** or the green plus icon to add a new webhook * Click **Create subscription** or the green plus icon to add a new webhook
- Scroll to the bottom of the list and select **Web Hooks** * Scroll to the bottom of the list and select **Web Hooks**
- Click **Next** * Click **Next**
- Under "Trigger on this type of event", select **Pull request created** * Under "Trigger on this type of event", select **Pull request created**
- Optionally, select a repository under **Filters** to restrict the scope of this webhook subscription to a specific repository * Optionally, select a repository under **Filters** to restrict the scope of this webhook subscription to a specific repository
- Click **Next** * Click **Next**
- Set **URL** to `http://$URL/events` where `$URL` is where Atlantis is hosted. Note that SSL, or `https://$URL/events`, is required if you set a Basic username and password for the webhook). **Be sure to add `/events`** * Set **URL** to `http://$URL/events` where `$URL` is where Atlantis is hosted. Note that SSL, or `https://$URL/events`, is required if you set a Basic username and password for the webhook). **Be sure to add `/events`**
- It is strongly recommended to set a Basic Username and Password for all webhooks * It is strongly recommended to set a Basic Username and Password for all webhooks
- Leave all three drop-down menus for `...to send` set to **All** * Leave all three drop-down menus for `...to send` set to **All**
- Resource version should be set to **1.0** for `Pull request created` and `Pull request updated` event types and **2.0** for `Pull request commented on` * Resource version should be set to **1.0** for `Pull request created` and `Pull request updated` event types and **2.0** for `Pull request commented on`
- **NOTE** If you're adding a webhook to multiple team projects or repositories (using filters), each repository will need to use the **same** basic username and password. * **NOTE** If you're adding a webhook to multiple team projects or repositories (using filters), each repository will need to use the **same** basic username and password.
- Click **Finish** * Click **Finish**
Repeat the process above until you have webhook subscriptions for the following event types that will trigger on all repositories Atlantis will manage: Repeat the process above until you have webhook subscriptions for the following event types that will trigger on all repositories Atlantis will manage:
- Pull request created (you just added this one) * Pull request created (you just added this one)
- Pull request updated * Pull request updated
- Pull request commented on * Pull request commented on
- See [Next Steps](#next-steps) * See [Next Steps](#next-steps)
## Next Steps ## Next Steps
* To verify that Atlantis is receiving your webhooks, create a test pull request to your repo. * To verify that Atlantis is receiving your webhooks, create a test pull request to your repo.
* You should see the request show up in the Atlantis logs at an `INFO` level. * You should see the request show up in the Atlantis logs at an `INFO` level.
* You'll now need to configure Atlantis to add your [Provider Credentials](provider-credentials.md) * You'll now need to configure Atlantis to add your [Provider Credentials](provider-credentials.md)

8
runatlantis.io/docs/custom-policy-checks.md
View File

@@ -1,9 +1,11 @@
# Custom Policy Checks # Custom Policy Checks
If you want to run custom policy tools or scripts instead of the built-in Conftest integration, you can do so by setting the `custom_policy_check` option and running it in a custom workflow. Note: custom policy tool output is simply parsed for "fail" substrings to determine if the policy set passed.
This option can be configured either at the server-level in a [repos.yaml config file](server-configuration.md) or at the repo-level in an [atlantis.yaml file.](repo-level-atlantis-yaml.md). If you want to run custom policy tools or scripts instead of the built-in Conftest integration, you can do so by setting the `custom_policy_check` option and running it in a custom workflow. Note: custom policy tool output is simply parsed for "fail" substrings to determine if the policy set passed.
This option can be configured either at the server-level in a [repos.yaml config file](server-configuration.md) or at the repo-level in an [atlantis.yaml file.](repo-level-atlantis-yaml.md).
## Server-side config example ## Server-side config example
Set the `policy_check` and `custom_policy_check` options to true, and run the custom tool in the policy check steps as seen below. Set the `policy_check` and `custom_policy_check` options to true, and run the custom tool in the policy check steps as seen below.
```yaml ```yaml
@@ -30,8 +32,8 @@ policies:
source: local source: local
``` ```
## Repo-level atlantis.yaml example ## Repo-level atlantis.yaml example
First, you will need to ensure `custom_policy_check` is within the `allowed_overrides` field of the server-side config. Next, just set the custom option to true on the specific project you want as shown in the example `atlantis.yaml` below: First, you will need to ensure `custom_policy_check` is within the `allowed_overrides` field of the server-side config. Next, just set the custom option to true on the specific project you want as shown in the example `atlantis.yaml` below:
```yaml ```yaml

146
runatlantis.io/docs/custom-workflows.md
View File

@@ -3,22 +3,25 @@
Custom workflows can be defined to override the default commands that Atlantis Custom workflows can be defined to override the default commands that Atlantis
runs. runs.
## Usage ## Usage
Custom workflows can be specified in the Server-Side Repo Config or in the Repo-Level Custom workflows can be specified in the Server-Side Repo Config or in the Repo-Level
`atlantis.yaml` files. `atlantis.yaml` files.
**Notes** **Notes:**
* If you want to allow repos to select their own workflows, they must have the * If you want to allow repos to select their own workflows, they must have the
`allowed_overrides: [workflow]` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-choose-a-server-side-workflow) for more details. `allowed_overrides: [workflow]` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-choose-a-server-side-workflow) for more details.
* If in addition you also want to allow repos to define their own workflows, they must have the * If in addition you also want to allow repos to define their own workflows, they must have the
`allow_custom_workflows: true` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-define-their-own-workflows) for more details. `allow_custom_workflows: true` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-define-their-own-workflows) for more details.
## Use Cases ## Use Cases
### .tfvars files ### .tfvars files
Given the structure: Given the structure:
```
```plain
. .
└── project1 └── project1
├── main.tf ├── main.tf
@@ -28,6 +31,7 @@ Given the structure:
If you wanted Atlantis to automatically run plan with `-var-file staging.tfvars` and `-var-file production.tfvars` If you wanted Atlantis to automatically run plan with `-var-file staging.tfvars` and `-var-file production.tfvars`
you could define two workflows: you could define two workflows:
```yaml ```yaml
# repos.yaml or atlantis.yaml # repos.yaml or atlantis.yaml
workflows: workflows:
@@ -39,7 +43,7 @@ workflows:
extra_args: ["-var-file", "staging.tfvars"] extra_args: ["-var-file", "staging.tfvars"]
# NOTE: no need to define the apply stage because it will default # NOTE: no need to define the apply stage because it will default
# to the normal apply stage. # to the normal apply stage.
production: production:
plan: plan:
steps: steps:
@@ -61,7 +65,9 @@ workflows:
- state_rm: - state_rm:
extra_args: ["-lock=false"] extra_args: ["-lock=false"]
``` ```
Then in your repo-level `atlantis.yaml` file, you would reference the workflows: Then in your repo-level `atlantis.yaml` file, you would reference the workflows:
```yaml ```yaml
# atlantis.yaml # atlantis.yaml
version: 3 version: 3
@@ -79,20 +85,27 @@ workflows:
# If you didn't define the workflows in your server-side repos.yaml config, # If you didn't define the workflows in your server-side repos.yaml config,
# you would define them here instead. # you would define them here instead.
``` ```
When you want to apply the plans, you can comment When you want to apply the plans, you can comment
```
```shell
atlantis apply -p project1-staging atlantis apply -p project1-staging
``` ```
and and
```
```shell
atlantis apply -p project1-production atlantis apply -p project1-production
``` ```
Where `-p` refers to the project name. Where `-p` refers to the project name.
### Adding extra arguments to Terraform commands ### Adding extra arguments to Terraform commands
If you need to append flags to `terraform plan` or `apply` temporarily, you can If you need to append flags to `terraform plan` or `apply` temporarily, you can
append flags on a comment following `--`, for example commenting: append flags on a comment following `--`, for example commenting:
```
```shell
atlantis plan -- -lock=false atlantis plan -- -lock=false
``` ```
@@ -129,6 +142,7 @@ workflows:
``` ```
### Custom init/plan/apply Commands ### Custom init/plan/apply Commands
If you want to customize `terraform init`, `plan` or `apply` in ways that If you want to customize `terraform init`, `plan` or `apply` in ways that
aren't supported by `extra_args`, you can completely override those commands. aren't supported by `extra_args`, you can completely override those commands.
@@ -146,11 +160,11 @@ workflows:
- run: - run:
command: terraform init -input=false command: terraform init -input=false
output: hide output: hide
# If you're using workspaces you need to select the workspace using the # If you're using workspaces you need to select the workspace using the
# $WORKSPACE environment variable. # $WORKSPACE environment variable.
- run: terraform workspace select $WORKSPACE - run: terraform workspace select $WORKSPACE
# You MUST output the plan using -out $PLANFILE because Atlantis expects # You MUST output the plan using -out $PLANFILE because Atlantis expects
# plans to be in a specific location. # plans to be in a specific location.
- run: terraform plan -input=false -refresh -out $PLANFILE - run: terraform plan -input=false -refresh -out $PLANFILE
@@ -161,14 +175,15 @@ workflows:
``` ```
### CDKTF ### CDKTF
Here are the requirements to enable [CDKTF](https://developer.hashicorp.com/terraform/cdktf) Here are the requirements to enable [CDKTF](https://developer.hashicorp.com/terraform/cdktf)
- A custom image with `CDKTF` installed * A custom image with `CDKTF` installed
- Add `**/cdk.tf.json` to the list of Atlantis autoplan files. * Add `**/cdk.tf.json` to the list of Atlantis autoplan files.
- Set the `atlantis-include-git-untracked-files` flag so that the Terraform files dynamically generated * Set the `atlantis-include-git-untracked-files` flag so that the Terraform files dynamically generated
by CDKTF will be add to the Atlantis modified file list. by CDKTF will be add to the Atlantis modified file list.
- Use `pre_workflow_hooks` to run `cdktf synth` * Use `pre_workflow_hooks` to run `cdktf synth`
- Optional: There isn't a requirement to use a repo `atlantis.yaml` but one can be leveraged if needed. * Optional: There isn't a requirement to use a repo `atlantis.yaml` but one can be leveraged if needed.
#### Custom Image #### Custom Image
@@ -191,6 +206,7 @@ ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true
OR OR
`atlantis server --config config.yaml` `atlantis server --config config.yaml`
```yaml ```yaml
# config.yaml # config.yaml
autoplan-file-list: "**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json" autoplan-file-list: "**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json"
@@ -202,6 +218,7 @@ include-git-untracked-files: true
Use `pre_workflow_hooks` Use `pre_workflow_hooks`
`atlantis server --repo-config="repos.yaml"` `atlantis server --repo-config="repos.yaml"`
```yaml ```yaml
# repos.yaml # repos.yaml
repos: repos:
@@ -233,7 +250,7 @@ $ tree --gitignore
1. Container orchestrator (k8s/fargate/ecs/etc) uses the custom docker image of atlantis with `cdktf` installed with 1. Container orchestrator (k8s/fargate/ecs/etc) uses the custom docker image of atlantis with `cdktf` installed with
the `--autoplan-file-list` to trigger on `cdk.tf.json` files and `--include-git-untracked-files` set to include the the `--autoplan-file-list` to trigger on `cdk.tf.json` files and `--include-git-untracked-files` set to include the
CDKTF dynamically generated Terraform files in the Atlantis plan. CDKTF dynamically generated Terraform files in the Atlantis plan.
1. PR branch is pushed up containing `cdktf` code changes. 1. PR branch is pushed up containing `cdktf` code changes.
1. Atlantis checks out the branch in the repo. 1. Atlantis checks out the branch in the repo.
1. Atlantis runs the `npm i && cdktf get && cdktf synth` command in the repo root as a step in `pre_workflow_hooks`, 1. Atlantis runs the `npm i && cdktf get && cdktf synth` command in the repo root as a step in `pre_workflow_hooks`,
@@ -242,6 +259,7 @@ generating the `cdk.tf.json` Terraform files.
1. Atlantis then runs `terraform` workflows in the respective directories as usual. 1. Atlantis then runs `terraform` workflows in the respective directories as usual.
### Terragrunt ### Terragrunt
Atlantis supports running custom commands in place of the default Atlantis Atlantis supports running custom commands in place of the default Atlantis
commands. We can use this functionality to enable commands. We can use this functionality to enable
[Terragrunt](https://github.com/gruntwork-io/terragrunt). [Terragrunt](https://github.com/gruntwork-io/terragrunt).
@@ -249,7 +267,8 @@ commands. We can use this functionality to enable
You can either use your repo's `atlantis.yaml` file or the Atlantis server's `repos.yaml` file. You can either use your repo's `atlantis.yaml` file or the Atlantis server's `repos.yaml` file.
Given a directory structure: Given a directory structure:
```
```plain
. .
└── live └── live
   ├── prod    ├── prod
@@ -314,6 +333,7 @@ workflows:
``` ```
If using the repo's `atlantis.yaml` file you would use the following config: If using the repo's `atlantis.yaml` file you would use the following config:
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -349,7 +369,6 @@ workflows:
**NOTE:** If using the repo's `atlantis.yaml` file, you will need to specify each directory that is a Terragrunt project. **NOTE:** If using the repo's `atlantis.yaml` file, you will need to specify each directory that is a Terragrunt project.
::: warning ::: warning
Atlantis will need to have the `terragrunt` binary in its PATH. Atlantis will need to have the `terragrunt` binary in its PATH.
If you're using Docker you can build your own image, see [Customization](deployment.md#customization). If you're using Docker you can build your own image, see [Customization](deployment.md#customization).
@@ -360,6 +379,7 @@ If you don't want to create/manage the repo's `atlantis.yaml` file yourself, you
The `terragrunt-atlantis-config` tool is a community project and not maintained by the Atlantis team. The `terragrunt-atlantis-config` tool is a community project and not maintained by the Atlantis team.
### Running custom commands ### Running custom commands
Atlantis supports running completely custom commands. In this example, we want to run Atlantis supports running completely custom commands. In this example, we want to run
a script after every `apply`: a script after every `apply`:
@@ -374,17 +394,19 @@ workflows:
``` ```
::: tip Notes ::: tip Notes
* We don't need to write a `plan` key under `myworkflow`. If `plan` * We don't need to write a `plan` key under `myworkflow`. If `plan`
isn't set, Atlantis will use the default plan workflow which is what we want in this case. isn't set, Atlantis will use the default plan workflow which is what we want in this case.
* A custom command will only terminate if all output file descriptors are closed. * A custom command will only terminate if all output file descriptors are closed.
Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during
the terraform run) when its output is redirected to a different location. For example, Atlantis the terraform run) when its output is redirected to a different location. For example, Atlantis
will execute a custom script containing the following code to create a SSH tunnel correctly: will execute a custom script containing the following code to create a SSH tunnel correctly:
`ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without `ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without
the redirect, the script would block the Atlantis workflow. the redirect, the script would block the Atlantis workflow.
::: :::
### Custom Backend Config ### Custom Backend Config
If you need to specify the `-backend-config` flag to `terraform init` you'll need to use a custom workflow. If you need to specify the `-backend-config` flag to `terraform init` you'll need to use a custom workflow.
In this example, we're using custom backend files to configure two remote states, one for each environment. In this example, we're using custom backend files to configure two remote states, one for each environment.
We're then using `.tfvars` files to load different variables for each environment. We're then using `.tfvars` files to load different variables for each environment.
@@ -409,12 +431,14 @@ workflows:
- plan: - plan:
extra_args: [-var-file=production.tfvars] extra_args: [-var-file=production.tfvars]
``` ```
::: warning NOTE ::: warning NOTE
We have to use a custom `run` step to `rm -rf .terraform` because otherwise Terraform We have to use a custom `run` step to `rm -rf .terraform` because otherwise Terraform
will complain in-between commands since the backend config has changed. will complain in-between commands since the backend config has changed.
::: :::
You would then reference the workflows in your repo-level `atlantis.yaml`: You would then reference the workflows in your repo-level `atlantis.yaml`:
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -427,7 +451,9 @@ projects:
``` ```
## Reference ## Reference
### Workflow ### Workflow
```yaml ```yaml
plan: plan:
apply: apply:
@@ -443,6 +469,7 @@ state_rm:
| state_rm | [Stage](#stage) | `steps: [init, state_rm]` | no | How to run state rm for this project. | | state_rm | [Stage](#stage) | `steps: [init, state_rm]` | no | How to run state rm for this project. |
### Stage ### Stage
```yaml ```yaml
steps: steps:
- run: custom-command - run: custom-command
@@ -456,8 +483,11 @@ steps:
| steps | array[[Step](#step)] | `[]` | no | List of steps for this stage. If the steps key is empty, no steps will be run for this stage. | | steps | array[[Step](#step)] | `[]` | no | List of steps for this stage. If the steps key is empty, no steps will be run for this stage. |
### Step ### Step
#### Built-In Commands #### Built-In Commands
Steps can be a single string for a built-in command. Steps can be a single string for a built-in command.
```yaml ```yaml
- init - init
- plan - plan
@@ -465,12 +495,15 @@ Steps can be a single string for a built-in command.
- import - import
- state_rm - state_rm
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|---------------------------------|--------|---------|----------|------------------------------------------------------------------------------------------------------------------------------| |---------------------------------|--------|---------|----------|------------------------------------------------------------------------------------------------------------------------------|
| init/plan/apply/import/state_rm | string | none | no | Use a built-in command without additional configuration. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported | | init/plan/apply/import/state_rm | string | none | no | Use a built-in command without additional configuration. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported |
#### Built-In Command With Extra Args #### Built-In Command With Extra Args
A map from string to `extra_args` for a built-in command with extra arguments. A map from string to `extra_args` for a built-in command with extra arguments.
```yaml ```yaml
- init: - init:
extra_args: [arg1, arg2] extra_args: [arg1, arg2]
@@ -483,79 +516,88 @@ A map from string to `extra_args` for a built-in command with extra arguments.
- state_rm: - state_rm:
extra_args: [arg1, arg2] extra_args: [arg1, arg2]
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|---------------------------------|------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |---------------------------------|------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| init/plan/apply/import/state_rm | map[`extra_args` -> array[string]] | none | no | Use a built-in command and append `extra_args`. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported as keys and only `extra_args` is supported as a value | | init/plan/apply/import/state_rm | map\[`extra_args` -> array\[string\]\] | none | no | Use a built-in command and append `extra_args`. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported as keys and only `extra_args` is supported as a value |
#### Custom `run` Command #### Custom `run` Command
A custom command can be written in 2 ways A custom command can be written in 2 ways
Compact: Compact:
```yaml ```yaml
- run: custom-command arg1 arg2 - run: custom-command arg1 arg2
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|-----|--------|---------|----------|----------------------| |-----|--------|---------|----------|----------------------|
| run | string | none | no | Run a custom command | | run | string | none | no | Run a custom command |
Full Full
```yaml ```yaml
- run: - run:
command: custom-command arg1 arg2 command: custom-command arg1 arg2
output: show output: show
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|-----|--------------------------------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-----|--------------------------------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| run | map[string -> string] | none | no | Run a custom command | | run | map\[string -> string\] | none | no | Run a custom command |
| run.command | string | none | yes | Shell command to run | | run.command | string | none | yes | Shell command to run |
| run.output | string | "show" | no | How to post-process the output of this command when posted in the PR comment. The options are<br/>* `show` - preserve the full output<br/>* `hide` - hide output from comment (still visible in the real-time streaming output)<br/> * `strip_refreshing` - hide all output up until and including the last line containing "Refreshing...". This matches the behavior of the built-in `plan` command | | run.output | string | "show" | no | How to post-process the output of this command when posted in the PR comment. The options are<br/>*`show` - preserve the full output<br/>* `hide` - hide output from comment (still visible in the real-time streaming output)<br/> * `strip_refreshing` - hide all output up until and including the last line containing "Refreshing...". This matches the behavior of the built-in `plan` command |
::: tip Notes ::: tip Notes
* `run` steps in the main `workflow` are executed with the following environment variables:
* `run` steps in the main `workflow` are executed with the following environment variables:
note: these variables are not available to `pre` or `post` workflows note: these variables are not available to `pre` or `post` workflows
* `WORKSPACE` - The Terraform workspace used for this project, ex. `default`. * `WORKSPACE` - The Terraform workspace used for this project, ex. `default`.
NOTE: if the step is executed before `init` then Atlantis won't have switched to this workspace yet. NOTE: if the step is executed before `init` then Atlantis won't have switched to this workspace yet.
* `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`. * `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`.
* `DIR` - Absolute path to the current directory. * `DIR` - Absolute path to the current directory.
* `PLANFILE` - Absolute path to the location where Atlantis expects the plan to * `PLANFILE` - Absolute path to the location where Atlantis expects the plan to
either be generated (by plan) or already exist (if running apply). Can be used to either be generated (by plan) or already exist (if running apply). Can be used to
override the built-in `plan`/`apply` commands, ex. `run: terraform plan -out $PLANFILE`. override the built-in `plan`/`apply` commands, ex. `run: terraform plan -out $PLANFILE`.
* `SHOWFILE` - Absolute path to the location where Atlantis expects the plan in json format to * `SHOWFILE` - Absolute path to the location where Atlantis expects the plan in json format to
either be generated (by show) or already exist (if running policy checks). Can be used to either be generated (by show) or already exist (if running policy checks). Can be used to
override the built-in `plan`/`apply` commands, ex. `run: terraform show -json $PLANFILE > $SHOWFILE`. override the built-in `plan`/`apply` commands, ex. `run: terraform show -json $PLANFILE > $SHOWFILE`.
* `POLICYCHECKFILE` - Absolute path to the location of policy check output if Atlantis runs policy checks. * `POLICYCHECKFILE` - Absolute path to the location of policy check output if Atlantis runs policy checks.
See [policy checking](policy-checking.md#data-for-custom-run-steps) for information of data structure. See [policy checking](policy-checking.md#data-for-custom-run-steps) for information of data structure.
* `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`. * `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`.
* `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`. * `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`.
* `HEAD_REPO_NAME` - Name of the repository that is getting merged into the base repository, ex. `atlantis`. * `HEAD_REPO_NAME` - Name of the repository that is getting merged into the base repository, ex. `atlantis`.
* `HEAD_REPO_OWNER` - Owner of the repository that is getting merged into the base repository, ex. `acme-corp`. * `HEAD_REPO_OWNER` - Owner of the repository that is getting merged into the base repository, ex. `acme-corp`.
* `HEAD_BRANCH_NAME` - Name of the head branch of the pull request (the branch that is getting merged into the base) * `HEAD_BRANCH_NAME` - Name of the head branch of the pull request (the branch that is getting merged into the base)
* `HEAD_COMMIT` - The sha256 that points to the head of the branch that is being pull requested into the base. If the pull request is from Bitbucket Cloud the string will only be 12 characters long because Bitbucket Cloud truncates its commit IDs. * `HEAD_COMMIT` - The sha256 that points to the head of the branch that is being pull requested into the base. If the pull request is from Bitbucket Cloud the string will only be 12 characters long because Bitbucket Cloud truncates its commit IDs.
* `BASE_BRANCH_NAME` - Name of the base branch of the pull request (the branch that the pull request is getting merged into) * `BASE_BRANCH_NAME` - Name of the base branch of the pull request (the branch that the pull request is getting merged into)
* `PROJECT_NAME` - Name of the project configured in `atlantis.yaml`. If no project name is configured this will be an empty string. * `PROJECT_NAME` - Name of the project configured in `atlantis.yaml`. If no project name is configured this will be an empty string.
* `PULL_NUM` - Pull request number or ID, ex. `2`. * `PULL_NUM` - Pull request number or ID, ex. `2`.
* `PULL_URL` - Pull request URL, ex. `https://github.com/runatlantis/atlantis/pull/2`. * `PULL_URL` - Pull request URL, ex. `https://github.com/runatlantis/atlantis/pull/2`.
* `PULL_AUTHOR` - Username of the pull request author, ex. `acme-user`. * `PULL_AUTHOR` - Username of the pull request author, ex. `acme-user`.
* `REPO_REL_DIR` - The relative path of the project in the repository. For example if your project is in `dir1/dir2/` then this will be set to `"dir1/dir2"`. If your project is at the root this will be `"."`. * `REPO_REL_DIR` - The relative path of the project in the repository. For example if your project is in `dir1/dir2/` then this will be set to `"dir1/dir2"`. If your project is at the root this will be `"."`.
* `USER_NAME` - Username of the VCS user running command, ex. `acme-user`. During an autoplan, the user will be the Atlantis API user, ex. `atlantis`. * `USER_NAME` - Username of the VCS user running command, ex. `acme-user`. During an autoplan, the user will be the Atlantis API user, ex. `atlantis`.
* `COMMENT_ARGS` - Any additional flags passed in the comment on the pull request. Flags are separated by commas and * `COMMENT_ARGS` - Any additional flags passed in the comment on the pull request. Flags are separated by commas and
every character is escaped, ex. `atlantis plan -- arg1 arg2` will result in `COMMENT_ARGS=\a\r\g\1,\a\r\g\2`. every character is escaped, ex. `atlantis plan -- arg1 arg2` will result in `COMMENT_ARGS=\a\r\g\1,\a\r\g\2`.
* A custom command will only terminate if all output file descriptors are closed. * A custom command will only terminate if all output file descriptors are closed.
Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during
the terraform run) when its output is redirected to a different location. For example, Atlantis the terraform run) when its output is redirected to a different location. For example, Atlantis
will execute a custom script containing the following code to create a SSH tunnel correctly: will execute a custom script containing the following code to create a SSH tunnel correctly:
`ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without `ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without
the redirect, the script would block the Atlantis workflow. the redirect, the script would block the Atlantis workflow.
* If a workflow step returns a non-zero exit code, the workflow will stop. * If a workflow step returns a non-zero exit code, the workflow will stop.
::: :::
#### Environment Variable `env` Command #### Environment Variable `env` Command
The `env` command allows you to set environment variables that will be available The `env` command allows you to set environment variables that will be available
to all steps defined **below** the `env` step. to all steps defined **below** the `env` step.
You can set hard coded values via the `value` key, or set dynamic values via You can set hard coded values via the `value` key, or set dynamic values via
the `command` key which allows you to run any command and uses the output the `command` key which allows you to run any command and uses the output
as the environment variable value. as the environment variable value.
```yaml ```yaml
- env: - env:
name: ENV_NAME name: ENV_NAME
@@ -564,24 +606,29 @@ as the environment variable value.
name: ENV_NAME_2 name: ENV_NAME_2
command: 'echo "dynamic-value-$(date)"' command: 'echo "dynamic-value-$(date)"'
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|-----------------|-----------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------| |-----------------|-----------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
| env | map[string -> string] | none | no | Set environment variables for subsequent steps | | env | map\[string -> string\] | none | no | Set environment variables for subsequent steps |
| env.name | string | none | yes | Name of the environment variable | | env.name | string | none | yes | Name of the environment variable |
| env.value | string | none | no | Set the value of the environment variable to a hard-coded string. Cannot be set at the same time as `command` | | env.value | string | none | no | Set the value of the environment variable to a hard-coded string. Cannot be set at the same time as `command` |
| env.command | string | none | no | Set the value of the environment variable to the output of a command. Cannot be set at the same time as `value` | | env.command | string | none | no | Set the value of the environment variable to the output of a command. Cannot be set at the same time as `value` |
::: tip Notes ::: tip Notes
* `env` `command`'s can use any of the built-in environment variables available * `env` `command`'s can use any of the built-in environment variables available
to `run` commands. to `run` commands.
::: :::
#### Multiple Environment Variables `multienv` Command #### Multiple Environment Variables `multienv` Command
The `multienv` command allows you to set dynamic number of multiple environment variables that will be available The `multienv` command allows you to set dynamic number of multiple environment variables that will be available
to all steps defined **below** the `multienv` step. to all steps defined **below** the `multienv` step.
```yaml ```yaml
- multienv: custom-command - multienv: custom-command
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|----------|--------|---------|----------|--------------------------------------------------------------------------------| |----------|--------|---------|----------|--------------------------------------------------------------------------------|
| multienv | string | none | no | Run a custom command and add set environment variables according to the result | | multienv | string | none | no | Run a custom command and add set environment variables according to the result |
@@ -592,6 +639,7 @@ EnvVar1Name=value1,EnvVar2Name=value2,EnvVar3Name=value3
The name-value pairs in the result are added as environment variables if success is true otherwise the workflow execution stops with error and the errorMessage is getting displayed. The name-value pairs in the result are added as environment variables if success is true otherwise the workflow execution stops with error and the errorMessage is getting displayed.
::: tip Notes ::: tip Notes
* `multienv` `command`'s can use any of the built-in environment variables available * `multienv` `command`'s can use any of the built-in environment variables available
to `run` commands. to `run` commands.
::: :::

72
runatlantis.io/docs/deployment.md
View File

@@ -1,19 +1,23 @@
# Deployment # Deployment
This page covers getting Atlantis up and running in your infrastructure. This page covers getting Atlantis up and running in your infrastructure.
::: tip Prerequisites ::: tip Prerequisites
* You have created [access credentials](access-credentials.md) for your Atlantis user * You have created [access credentials](access-credentials.md) for your Atlantis user
* You have created a [webhook secret](webhook-secrets.md) * You have created a [webhook secret](webhook-secrets.md)
::: :::
## Architecture Overview ## Architecture Overview
### Runtime ### Runtime
Atlantis is a simple [Go](https://golang.org/) app. It receives webhooks from Atlantis is a simple [Go](https://golang.org/) app. It receives webhooks from
your Git host and executes Terraform commands locally. There is an official your Git host and executes Terraform commands locally. There is an official
Atlantis [Docker image](https://ghcr.io/runatlantis/atlantis). Atlantis [Docker image](https://ghcr.io/runatlantis/atlantis).
### Routing ### Routing
Atlantis and your Git host need to be able to route and communicate with one another. Your Git host needs to be able to send webhooks to Atlantis and Atlantis needs to be able to make API calls to your Git host. Atlantis and your Git host need to be able to route and communicate with one another. Your Git host needs to be able to send webhooks to Atlantis and Atlantis needs to be able to make API calls to your Git host.
If you're using If you're using
a public Git host like github.com, gitlab.com, gitea.com, bitbucket.org, or dev.azure.com then you'll need to a public Git host like github.com, gitlab.com, gitea.com, bitbucket.org, or dev.azure.com then you'll need to
@@ -23,6 +27,7 @@ If you're using a private Git host like GitHub Enterprise, GitLab Enterprise, se
Bitbucket Server, then Atlantis needs to be routable from the private host and Atlantis will need to be able to route to the private host. Bitbucket Server, then Atlantis needs to be routable from the private host and Atlantis will need to be able to route to the private host.
### Data ### Data
Atlantis has no external database. Atlantis stores Terraform plan files on disk. Atlantis has no external database. Atlantis stores Terraform plan files on disk.
If Atlantis loses that data in between a `plan` and `apply` cycle, then users will have If Atlantis loses that data in between a `plan` and `apply` cycle, then users will have
to re-run `plan`. Because of this, you may want to provision a persistent disk to re-run `plan`. Because of this, you may want to provision a persistent disk
@@ -31,6 +36,7 @@ for Atlantis.
## Deployment ## Deployment
Pick your deployment type: Pick your deployment type:
* [Kubernetes Helm Chart](#kubernetes-helm-chart) * [Kubernetes Helm Chart](#kubernetes-helm-chart)
* [Kubernetes Manifests](#kubernetes-manifests) * [Kubernetes Manifests](#kubernetes-manifests)
* [Kubernetes Kustomize](#kubernetes-kustomize) * [Kubernetes Kustomize](#kubernetes-kustomize)
@@ -40,21 +46,27 @@ Pick your deployment type:
* [Docker](#docker) * [Docker](#docker)
* [Roll Your Own](#roll-your-own) * [Roll Your Own](#roll-your-own)
### Kubernetes Helm Chart ### Kubernetes Helm Chart
Atlantis has an [official Helm chart](https://github.com/runatlantis/helm-charts/tree/main/charts/atlantis) Atlantis has an [official Helm chart](https://github.com/runatlantis/helm-charts/tree/main/charts/atlantis)
To install: To install:
1. Add the runatlantis helm chart repository to helm 1. Add the runatlantis helm chart repository to helm
```bash ```bash
helm repo add runatlantis https://runatlantis.github.io/helm-charts helm repo add runatlantis https://runatlantis.github.io/helm-charts
``` ```
1. `cd` into a directory where you're going to configure your Atlantis Helm chart 1. `cd` into a directory where you're going to configure your Atlantis Helm chart
1. Create a `values.yaml` file by running 1. Create a `values.yaml` file by running
```bash ```bash
helm inspect values runatlantis/atlantis > values.yaml helm inspect values runatlantis/atlantis > values.yaml
``` ```
1. Edit `values.yaml` and add your access credentials and webhook secret 1. Edit `values.yaml` and add your access credentials and webhook secret
```yaml ```yaml
# for example # for example
github: github:
@@ -62,28 +74,33 @@ To install:
token: bar token: bar
secret: baz secret: baz
``` ```
1. Edit `values.yaml` and set your `orgAllowlist` (see [Repo Allowlist](server-configuration.md#repo-allowlist) for more information) 1. Edit `values.yaml` and set your `orgAllowlist` (see [Repo Allowlist](server-configuration.md#repo-allowlist) for more information)
```yaml ```yaml
orgAllowlist: github.com/runatlantis/* orgAllowlist: github.com/runatlantis/*
``` ```
**Note**: For helm chart version < `4.0.2`, `orgWhitelist` must be used instead.
**Note**: For helm chart version < `4.0.2`, `orgWhitelist` must be used instead.
1. Configure any other variables (see [Atlantis Helm Chart: Customization](https://github.com/runatlantis/helm-charts#customization) 1. Configure any other variables (see [Atlantis Helm Chart: Customization](https://github.com/runatlantis/helm-charts#customization)
for documentation) for documentation)
1. Run 1. Run
```sh ```sh
helm install atlantis runatlantis/atlantis -f values.yaml helm install atlantis runatlantis/atlantis -f values.yaml
``` ```
If you are using helm v2, run: If you are using helm v2, run:
```sh ```sh
helm install -f values.yaml runatlantis/atlantis helm install -f values.yaml runatlantis/atlantis
``` ```
Atlantis should be up and running in minutes! See [Next Steps](#next-steps) for Atlantis should be up and running in minutes! See [Next Steps](#next-steps) for
what to do next. what to do next.
### Kubernetes Manifests ### Kubernetes Manifests
If you'd like to use a raw Kubernetes manifest, we offer either a If you'd like to use a raw Kubernetes manifest, we offer either a
[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
or a [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) with persistent storage. or a [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) with persistent storage.
@@ -93,16 +110,19 @@ or you upgrade Atlantis, you won't lose plans that haven't been applied. If
you do lose that data, you just need to run `atlantis plan` again so it's not the end of the world. you do lose that data, you just need to run `atlantis plan` again so it's not the end of the world.
Regardless of whether you choose a Deployment or StatefulSet, first create a Secret with the webhook secret and access token: Regardless of whether you choose a Deployment or StatefulSet, first create a Secret with the webhook secret and access token:
```bash ```bash
echo -n "yourtoken" > token echo -n "yourtoken" > token
echo -n "yoursecret" > webhook-secret echo -n "yoursecret" > webhook-secret
kubectl create secret generic atlantis-vcs --from-file=token --from-file=webhook-secret kubectl create secret generic atlantis-vcs --from-file=token --from-file=webhook-secret
``` ```
::: tip Note ::: tip Note
If you're using Bitbucket Cloud then there is no webhook secret since it's not supported. If you're using Bitbucket Cloud then there is no webhook secret since it's not supported.
::: :::
Next, edit the manifests below as follows: Next, edit the manifests below as follows:
1. Replace `<VERSION>` in `image: ghcr.io/runatlantis/atlantis:<VERSION>` with the most recent version from [GitHub: Atlantis latest release](https://github.com/runatlantis/atlantis/releases/latest). 1. Replace `<VERSION>` in `image: ghcr.io/runatlantis/atlantis:<VERSION>` with the most recent version from [GitHub: Atlantis latest release](https://github.com/runatlantis/atlantis/releases/latest).
* NOTE: You never want to run with `:latest` because if your Pod moves to a new node, Kubernetes will pull the latest image and you might end * NOTE: You never want to run with `:latest` because if your Pod moves to a new node, Kubernetes will pull the latest image and you might end
up upgrading Atlantis by accident! up upgrading Atlantis by accident!
@@ -125,6 +145,7 @@ for your Terraform repos. See [--repo-allowlist](server-configuration.md#repo-al
2. Delete all the `ATLANTIS_GH_*`, `ATLANTIS_GITLAB_*`, `ATLANTIS_GITEA_*`, and `ATLANTIS_BITBUCKET_*` environment variables. 2. Delete all the `ATLANTIS_GH_*`, `ATLANTIS_GITLAB_*`, `ATLANTIS_GITEA_*`, and `ATLANTIS_BITBUCKET_*` environment variables.
#### StatefulSet Manifest #### StatefulSet Manifest
<details> <details>
<summary>Show...</summary> <summary>Show...</summary>
@@ -289,10 +310,11 @@ spec:
selector: selector:
app.kubernetes.io/name: atlantis app.kubernetes.io/name: atlantis
``` ```
</details> </details>
#### Deployment Manifest #### Deployment Manifest
<details> <details>
<summary>Show...</summary> <summary>Show...</summary>
@@ -437,9 +459,11 @@ spec:
selector: selector:
app.kubernetes.io/name: atlantis app.kubernetes.io/name: atlantis
``` ```
</details> </details>
#### Routing and SSL #### Routing and SSL
The manifests above create a Kubernetes `Service` of `type: ClusterIP` which isn't accessible outside your cluster. The manifests above create a Kubernetes `Service` of `type: ClusterIP` which isn't accessible outside your cluster.
Depending on how you're doing routing into Kubernetes, you may want to use a Service of `type: LoadBalancer` so that Atlantis is accessible Depending on how you're doing routing into Kubernetes, you may want to use a Service of `type: LoadBalancer` so that Atlantis is accessible
to GitHub/GitLab and your internal users. to GitHub/GitLab and your internal users.
@@ -457,6 +481,7 @@ A `kustomization.yaml` file is provided in the directory `kustomize/`, so you ma
You will need to provide a secret (with the default name of `atlantis-vcs`) to configure Atlantis with access credentials for your remote repositories. You will need to provide a secret (with the default name of `atlantis-vcs`) to configure Atlantis with access credentials for your remote repositories.
Example: Example:
```yaml ```yaml
bases: bases:
- github.com/runatlantis/atlantis//kustomize - github.com/runatlantis/atlantis//kustomize
@@ -482,7 +507,6 @@ patchesStrategicMerge:
#### Required #### Required
```yaml ```yaml
... ...
containers: containers:
@@ -571,16 +595,19 @@ containers:
``` ```
### OpenShift ### OpenShift
The Helm chart and Kubernetes manifests above are compatible with OpenShift, however you need to run The Helm chart and Kubernetes manifests above are compatible with OpenShift, however you need to run
with an additional environment variable: `HOME=/home/atlantis`. This is required because with an additional environment variable: `HOME=/home/atlantis`. This is required because
OpenShift runs Docker images with random user id's that use `/` as their home directory. OpenShift runs Docker images with random user id's that use `/` as their home directory.
### AWS Fargate ### AWS Fargate
If you'd like to run Atlantis on [AWS Fargate](https://aws.amazon.com/fargate/) If you'd like to run Atlantis on [AWS Fargate](https://aws.amazon.com/fargate/)
check out the Atlantis module on the [Terraform Module Registry](https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws/latest) check out the Atlantis module on the [Terraform Module Registry](https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws/latest)
and then check out the [Next Steps](#next-steps). and then check out the [Next Steps](#next-steps).
### Google Kubernetes Engine (GKE) ### Google Kubernetes Engine (GKE)
You can run Atlantis on GKE using the [Helm chart](#kubernetes-helm-chart) or the [manifests](#kubernetes-manifests). You can run Atlantis on GKE using the [Helm chart](#kubernetes-helm-chart) or the [manifests](#kubernetes-manifests).
There is also a set of full Terraform configurations that create a GKE Cluster, There is also a set of full Terraform configurations that create a GKE Cluster,
@@ -589,19 +616,23 @@ Cloud Storage Backend and TLS certs: [sethvargo atlantis-on-gke](https://github.
Once you're done, see [Next Steps](#next-steps). Once you're done, see [Next Steps](#next-steps).
### Google Compute Engine (GCE) ### Google Compute Engine (GCE)
Atlantis can be run on Google Compute Engine using a Terraform module that deploys it as a Docker container on a managed Compute Engine instance.
Atlantis can be run on Google Compute Engine using a Terraform module that deploys it as a Docker container on a managed Compute Engine instance.
This [Terraform module](https://registry.terraform.io/modules/runatlantis/atlantis/gce/latest) features the creation of a Cloud load balancer, a Container-Optimized OS-based VM, a persistent data disk, and a managed instance group. This [Terraform module](https://registry.terraform.io/modules/runatlantis/atlantis/gce/latest) features the creation of a Cloud load balancer, a Container-Optimized OS-based VM, a persistent data disk, and a managed instance group.
After it is deployed, see [Next Steps](#next-steps). After it is deployed, see [Next Steps](#next-steps).
### Docker ### Docker
Atlantis has an [official](https://ghcr.io/runatlantis/atlantis) Docker image: `ghcr.io/runatlantis/atlantis`. Atlantis has an [official](https://ghcr.io/runatlantis/atlantis) Docker image: `ghcr.io/runatlantis/atlantis`.
#### Customization #### Customization
If you need to modify the Docker image that we provide, for instance to add the terragrunt binary, you can do something like this: If you need to modify the Docker image that we provide, for instance to add the terragrunt binary, you can do something like this:
1. Create a custom docker file 1. Create a custom docker file
```dockerfile ```dockerfile
FROM ghcr.io/runatlantis/atlantis:{latest version} FROM ghcr.io/runatlantis/atlantis:{latest version}
@@ -615,32 +646,37 @@ Additionally, the /docker-entrypoint.d/ directory offers a flexible option for i
**Important Notice**: There is a critical update regarding the data directory in Atlantis. In versions prior to 0.26.0, the directory was configured to be accessible by the root user. However, with the transition to the atlantis user in newer versions, it is imperative to update the directory permissions accordingly in your current deployment when upgrading to a version later than 0.26.0. This step ensures seamless access and functionality for the atlantis user. **Important Notice**: There is a critical update regarding the data directory in Atlantis. In versions prior to 0.26.0, the directory was configured to be accessible by the root user. However, with the transition to the atlantis user in newer versions, it is imperative to update the directory permissions accordingly in your current deployment when upgrading to a version later than 0.26.0. This step ensures seamless access and functionality for the atlantis user.
1. Build your Docker image 1. Build your Docker image
```bash ```bash
docker build -t {YOUR_DOCKER_ORG}/atlantis-custom . docker build -t {YOUR_DOCKER_ORG}/atlantis-custom .
``` ```
1. Run your image 1. Run your image
```bash ```bash
docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN
``` ```
### Microsoft Azure ### Microsoft Azure
The standard [Kubernetes Helm Chart](#kubernetes-helm-chart) should work fine on [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/intro-kubernetes). The standard [Kubernetes Helm Chart](#kubernetes-helm-chart) should work fine on [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/intro-kubernetes).
Another option is [Azure Container Instances](https://docs.microsoft.com/en-us/azure/container-instances/). See this community member's [repo](https://github.com/jplane/atlantis-on-aci) or the new and more up-to-date [Terraform module](https://github.com/getindata/terraform-azurerm-atlantis) for install scripts and more information on running Atlantis on ACI.
Another option is [Azure Container Instances](https://docs.microsoft.com/en-us/azure/container-instances/). See this community member's [repo](https://github.com/jplane/atlantis-on-aci) or the new and more up-to-date [Terraform module](https://github.com/getindata/terraform-azurerm-atlantis) for install scripts and more information on running Atlantis on ACI.
**Note on ACI Deployment:** Due to a bug in earlier Docker releases, Docker v23.0.0 or later is required for straightforward deployment. Alternatively, the Atlantis Docker image can be pushed to a private registry such as ACR and then used. **Note on ACI Deployment:** Due to a bug in earlier Docker releases, Docker v23.0.0 or later is required for straightforward deployment. Alternatively, the Atlantis Docker image can be pushed to a private registry such as ACR and then used.
### Roll Your Own ### Roll Your Own
If you want to roll your own Atlantis installation, you can get the `atlantis` If you want to roll your own Atlantis installation, you can get the `atlantis`
binary from [GitHub](https://github.com/runatlantis/atlantis/releases) binary from [GitHub](https://github.com/runatlantis/atlantis/releases)
or use the [official Docker image](https://ghcr.io/runatlantis/atlantis). or use the [official Docker image](https://ghcr.io/runatlantis/atlantis).
#### Startup Command #### Startup Command
The exact flags to `atlantis server` depends on your Git host: The exact flags to `atlantis server` depends on your Git host:
##### GitHub ##### GitHub
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -651,6 +687,7 @@ atlantis server \
``` ```
##### GitHub Enterprise ##### GitHub Enterprise
```bash ```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \ atlantis server \
@@ -663,6 +700,7 @@ atlantis server \
``` ```
##### GitLab ##### GitLab
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -673,6 +711,7 @@ atlantis server \
``` ```
##### GitLab Enterprise ##### GitLab Enterprise
```bash ```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \ atlantis server \
@@ -685,6 +724,7 @@ atlantis server \
``` ```
##### Gitea ##### Gitea
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -696,6 +736,7 @@ atlantis server \
``` ```
##### Bitbucket Cloud (bitbucket.org) ##### Bitbucket Cloud (bitbucket.org)
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -705,6 +746,7 @@ atlantis server \
``` ```
##### Bitbucket Server (aka Stash) ##### Bitbucket Server (aka Stash)
```bash ```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990 BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \ atlantis server \
@@ -733,20 +775,21 @@ atlantis server \
``` ```
Where Where
- `$URL` is the URL that Atlantis can be reached at
- `$USERNAME` is the GitHub/GitLab/Gitea/Bitbucket/AzureDevops username you generated the token for * `$URL` is the URL that Atlantis can be reached at
- `$TOKEN` is the access token you created. If you don't want this to be passed * `$USERNAME` is the GitHub/GitLab/Gitea/Bitbucket/AzureDevops username you generated the token for
* `$TOKEN` is the access token you created. If you don't want this to be passed
in as an argument for security reasons you can specify it in a config file in as an argument for security reasons you can specify it in a config file
(see [Configuration](server-configuration.md#environment-variables)) (see [Configuration](server-configuration.md#environment-variables))
or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN` or `ATLANTIS_GITEA_TOKEN` or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN` or `ATLANTIS_GITEA_TOKEN`
or `ATLANTIS_BITBUCKET_TOKEN` or `ATLANTIS_AZUREDEVOPS_TOKEN` or `ATLANTIS_BITBUCKET_TOKEN` or `ATLANTIS_AZUREDEVOPS_TOKEN`
- `$SECRET` is the random key you used for the webhook secret. * `$SECRET` is the random key you used for the webhook secret.
If you don't want this to be passed in as an argument for security reasons If you don't want this to be passed in as an argument for security reasons
you can specify it in a config file you can specify it in a config file
(see [Configuration](server-configuration.md#environment-variables)) (see [Configuration](server-configuration.md#environment-variables))
or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET` or or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET` or
`ATLANTIS_GITEA_WEBHOOK_SECRET` `ATLANTIS_GITEA_WEBHOOK_SECRET`
- `$REPO_ALLOWLIST` is which repos Atlantis can run on, ex. * `$REPO_ALLOWLIST` is which repos Atlantis can run on, ex.
`github.com/runatlantis/*` or `github.enterprise.corp.com/*`. `github.com/runatlantis/*` or `github.enterprise.corp.com/*`.
See [--repo-allowlist](server-configuration.md#repo-allowlist) for more details. See [--repo-allowlist](server-configuration.md#repo-allowlist) for more details.
@@ -757,5 +800,6 @@ restart it in case of failure.
::: :::
## Next Steps ## Next Steps
* To ensure Atlantis is running, load its UI. By default Atlantis runs on port `4141`. * To ensure Atlantis is running, load its UI. By default Atlantis runs on port `4141`.
* Now you're ready to add Webhooks to your repos. See [Configuring Webhooks](configuring-webhooks.md). * Now you're ready to add Webhooks to your repos. See [Configuring Webhooks](configuring-webhooks.md).

1
runatlantis.io/docs/faq.md
View File

@@ -1,4 +1,5 @@
# FAQ # FAQ
**Q: Does Atlantis affect Terraform [remote state](https://developer.hashicorp.com/terraform/language/state/remote)?** **Q: Does Atlantis affect Terraform [remote state](https://developer.hashicorp.com/terraform/language/state/remote)?**
A: No. Atlantis does not interfere with Terraform remote state in any way. Under the hood, Atlantis is simply executing `terraform plan` and `terraform apply`. A: No. Atlantis does not interfere with Terraform remote state in any way. Under the hood, Atlantis is simply executing `terraform plan` and `terraform apply`.

1
runatlantis.io/docs/how-atlantis-works.md
View File

@@ -1,4 +1,5 @@
# How Atlantis Works # How Atlantis Works
This section of docs talks about how Atlantis at deeper level. This section of docs talks about how Atlantis at deeper level.
* [Locking](locking.md) * [Locking](locking.md)

2
runatlantis.io/docs/installation-guide.md
View File

@@ -1,6 +1,8 @@
# Installation Guide # Installation Guide
This guide is for installing a **production-ready** instance of Atlantis onto your This guide is for installing a **production-ready** instance of Atlantis onto your
infrastructure: infrastructure:
1. First, ensure your Terraform setup meets the Atlantis **requirements** 1. First, ensure your Terraform setup meets the Atlantis **requirements**
* See [Requirements](requirements.md) * See [Requirements](requirements.md)
1. Create **access credentials** for your Git host (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps) 1. Create **access credentials** for your Git host (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps)

6
runatlantis.io/docs/locking.md
View File

@@ -1,4 +1,5 @@
# Locking # Locking
When `plan` is run, the directory and Terraform workspace are **Locked** until the pull request is merged or closed, or the plan is manually deleted. When `plan` is run, the directory and Terraform workspace are **Locked** until the pull request is merged or closed, or the plan is manually deleted.
If another user attempts to `plan` for the same directory and workspace in a different pull request If another user attempts to `plan` for the same directory and workspace in a different pull request
@@ -12,8 +13,8 @@ Which links them to the pull request that holds the lock.
Only the directory in the repo and Terraform workspace are locked, not the whole repo. Only the directory in the repo and Terraform workspace are locked, not the whole repo.
::: :::
## Why ## Why
1. Because `atlantis apply` is being done before the pull request is merged, after 1. Because `atlantis apply` is being done before the pull request is merged, after
an apply your `main` branch does not represent the most up to date version of your infrastructure an apply your `main` branch does not represent the most up to date version of your infrastructure
anymore. With locking, you can ensure that no other changes will be made until the anymore. With locking, you can ensure that no other changes will be made until the
@@ -29,6 +30,7 @@ but with the added ability to re-plan/apply multiple times if things don't work.
will be made invalid after the in-progress plan is applied. will be made invalid after the in-progress plan is applied.
## Viewing Locks ## Viewing Locks
To view locks, go to the URL that Atlantis is hosted at: To view locks, go to the URL that Atlantis is hosted at:
![Locks View](./images/locks-ui.png) ![Locks View](./images/locks-ui.png)
@@ -40,6 +42,7 @@ You can click on a lock to view its details:
</p> </p>
## Unlocking ## Unlocking
The project and workspace will be automatically unlocked when the PR is merged or closed. The project and workspace will be automatically unlocked when the PR is merged or closed.
To unlock the project and workspace without completing an `apply` and merging, comment `atlantis unlock` on the PR, To unlock the project and workspace without completing an `apply` and merging, comment `atlantis unlock` on the PR,
@@ -58,6 +61,7 @@ to delete the lock.
Once a plan is discarded, you'll need to run `plan` again prior to running `apply` when you go back to that pull request. Once a plan is discarded, you'll need to run `plan` again prior to running `apply` when you go back to that pull request.
## Relationship to Terraform State Locking ## Relationship to Terraform State Locking
Atlantis does not conflict with [Terraform State Locking](https://developer.hashicorp.com/terraform/language/state/locking). Under the hood, all Atlantis does not conflict with [Terraform State Locking](https://developer.hashicorp.com/terraform/language/state/locking). Under the hood, all
Atlantis is doing is running `terraform plan` and `apply` and so all of the Atlantis is doing is running `terraform plan` and `apply` and so all of the
locking built in to those commands by Terraform isn't affected. locking built in to those commands by Terraform isn't affected.

13
runatlantis.io/docs/policy-checking.md
View File

@@ -20,9 +20,9 @@ Any failures need to either be addressed in a successive commit, or approved by
![Policy Check Approval](./images/policy-check-approval.png) ![Policy Check Approval](./images/policy-check-approval.png)
Policy approvals may be cleared either by re-planing, or by issuing the following command: Policy approvals may be cleared either by re-planing, or by issuing the following command:
```
```shell
atlantis approve_policies --clear-policy-approval atlantis approve_policies --clear-policy-approval
``` ```
@@ -48,7 +48,7 @@ Policy Configuration is defined in the [server-side repo configuration](server-s
In this example we will define one policy set with one owner: In this example we will define one policy set with one owner:
``` ```yaml
policies: policies:
owners: owners:
users: users:
@@ -76,7 +76,7 @@ By default conftest is configured to only run the `main` package. If you wish to
Example Server Side Repo configuration using `--all-namespaces` and a local src dir. Example Server Side Repo configuration using `--all-namespaces` and a local src dir.
``` ```yaml
repos: repos:
- id: github.com/myorg/example-repo - id: github.com/myorg/example-repo
workflow: custom workflow: custom
@@ -104,7 +104,7 @@ workflows:
Conftest policies are based on [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) and written in [rego](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego). Following our example, simply create a `rego` file in `null_resource_warning` folder with following code, the code below a simple policy that will fail for plans containing newly created `null_resource`s. Conftest policies are based on [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) and written in [rego](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego). Following our example, simply create a `rego` file in `null_resource_warning` folder with following code, the code below a simple policy that will fail for plans containing newly created `null_resource`s.
``` ```rego
package main package main
resource_types = {"null_resource"} resource_types = {"null_resource"}
@@ -178,7 +178,6 @@ workflows:
By default, Atlantis will add a comment to all pull requests with the policy check result - both successes and failures. Version 0.21.0 added the [`--quiet-policy-checks`](server-configuration.md#quiet-policy-checks) option, which will instead only add comments when policy checks fail, significantly reducing the number of comments when most policy check results succeed. By default, Atlantis will add a comment to all pull requests with the policy check result - both successes and failures. Version 0.21.0 added the [`--quiet-policy-checks`](server-configuration.md#quiet-policy-checks) option, which will instead only add comments when policy checks fail, significantly reducing the number of comments when most policy check results succeed.
### Data for custom run steps ### Data for custom run steps
When the policy check workflow runs, a file is created in the working directory which contains information about the status of each policy set tested. This data may be useful in custom run steps to generate metrics or notifications. The file contains JSON data in the following format: When the policy check workflow runs, a file is created in the working directory which contains information about the status of each policy set tested. This data may be useful in custom run steps to generate metrics or notifications. The file contains JSON data in the following format:
@@ -201,6 +200,7 @@ When the policy check workflow runs, a file is created in the working directory
When policy checking is enabled it will be enforced on all repositories, in order to disable policy checking on some repositories first [enable policy checks](policy-checking.md#getting-started) and then disable it explicitly on each repository with the `policy_check` flag. When policy checking is enabled it will be enforced on all repositories, in order to disable policy checking on some repositories first [enable policy checks](policy-checking.md#getting-started) and then disable it explicitly on each repository with the `policy_check` flag.
For server side config: For server side config:
```yml ```yml
# repos.yaml # repos.yaml
repos: repos:
@@ -216,6 +216,7 @@ repos:
``` ```
For repo level `atlantis.yaml` config: For repo level `atlantis.yaml` config:
```yml ```yml
version: 3 version: 3
projects: projects:

3
runatlantis.io/docs/post-workflow-hooks.md
View File

@@ -6,7 +6,6 @@ workflows](custom-workflows.md#custom-run-command) in that they are run
outside of Atlantis commands. Which means they do not surface their output outside of Atlantis commands. Which means they do not surface their output
back to the PR as a comment. back to the PR as a comment.
## Usage ## Usage
Post workflow hooks can only be specified in the Server-Side Repo Config under Post workflow hooks can only be specified in the Server-Side Repo Config under
@@ -43,7 +42,6 @@ have finished.
In this example we use a custom workflow to generate cost estimates for each In this example we use a custom workflow to generate cost estimates for each
workflow using [Infracost](https://www.infracost.io/docs/integrations/cicd/#cicd-integrations), then create a summary report after all workflows have completed. workflow using [Infracost](https://www.infracost.io/docs/integrations/cicd/#cicd-integrations), then create a summary report after all workflows have completed.
```yaml ```yaml
# repos.yaml # repos.yaml
workflows: workflows:
@@ -101,6 +99,7 @@ command](custom-workflows.md#custom-run-command).
| shellArgs | string | '-c' | no | The shell arguments to use for running the command | | shellArgs | string | '-c' | no | The shell arguments to use for running the command |
::: tip Notes ::: tip Notes
* `run` commands are executed with the following environment variables: * `run` commands are executed with the following environment variables:
* `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`. * `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`.
* `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`. * `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`.

1
runatlantis.io/docs/pre-workflow-hooks.md
View File

@@ -9,7 +9,6 @@ workflows](custom-workflows.md#custom-run-command) in several ways.
2. Pre workflow hooks are run outside of Atlantis commands. Which means 2. Pre workflow hooks are run outside of Atlantis commands. Which means
they do not surface their output back to the PR as a comment. they do not surface their output back to the PR as a comment.
## Usage ## Usage
Pre workflow hooks can only be specified in the Server-Side Repo Config under the Pre workflow hooks can only be specified in the Server-Side Repo Config under the

12
runatlantis.io/docs/provider-credentials.md
View File

@@ -1,17 +1,19 @@
# Provider Credentials # Provider Credentials
Atlantis runs Terraform by simply executing `terraform plan` and `apply` commands Atlantis runs Terraform by simply executing `terraform plan` and `apply` commands
on the server Atlantis is hosted on. on the server Atlantis is hosted on.
Just like when you run Terraform locally, Atlantis needs credentials for your Just like when you run Terraform locally, Atlantis needs credentials for your
specific provider. specific provider.
It's up to you how you provide credentials for your specific provider to Atlantis: It's up to you how you provide credentials for your specific provider to Atlantis:
* The Atlantis [Helm Chart](deployment.md#kubernetes-helm-chart) and
* The Atlantis [Helm Chart](deployment.md#kubernetes-helm-chart) and
[AWS Fargate Module](deployment.md#aws-fargate) have their own mechanisms for provider [AWS Fargate Module](deployment.md#aws-fargate) have their own mechanisms for provider
credentials. Read their docs. credentials. Read their docs.
* If you're running Atlantis in a cloud then many clouds have ways to give cloud API access * If you're running Atlantis in a cloud then many clouds have ways to give cloud API access
to applications running on them, ex: to applications running on them, ex:
* [AWS EC2 Roles](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) (Search for "EC2 Role") * [AWS EC2 Roles](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) (Search for "EC2 Role")
* [GCE Instance Service Accounts](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) * [GCE Instance Service Accounts](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference)
* Many users set environment variables, ex. `AWS_ACCESS_KEY`, where Atlantis is running. * Many users set environment variables, ex. `AWS_ACCESS_KEY`, where Atlantis is running.
* Others create the necessary config files, ex. `~/.aws/credentials`, where Atlantis is running. * Others create the necessary config files, ex. `~/.aws/credentials`, where Atlantis is running.
* Use the [HashiCorp Vault Provider](https://registry.terraform.io/providers/hashicorp/vault/latest/docs) * Use the [HashiCorp Vault Provider](https://registry.terraform.io/providers/hashicorp/vault/latest/docs)
@@ -22,10 +24,10 @@ As a general rule, if you can `ssh` or `exec` into the server where Atlantis is
running and run `terraform` commands like you would locally, then Atlantis will work. running and run `terraform` commands like you would locally, then Atlantis will work.
::: :::
## AWS Specific Info ## AWS Specific Info
### Multiple AWS Accounts ### Multiple AWS Accounts
Atlantis supports multiple AWS accounts through the use of Terraform's Atlantis supports multiple AWS accounts through the use of Terraform's
[AWS Authentication](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) (Search for "Authentication"). [AWS Authentication](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) (Search for "Authentication").
@@ -41,6 +43,7 @@ won't work for multiple accounts since Atlantis wouldn't know which environment
Terraform with. Terraform with.
### Assume Role Session Names ### Assume Role Session Names
If you're using Terraform < 0.12, Atlantis injects 5 Terraform variables that can be used to dynamically name the assume role session name. If you're using Terraform < 0.12, Atlantis injects 5 Terraform variables that can be used to dynamically name the assume role session name.
Setting the `session_name` allows you to trace API calls made through Atlantis back to a specific Setting the `session_name` allows you to trace API calls made through Atlantis back to a specific
user and repo via CloudWatch: user and repo via CloudWatch:
@@ -89,5 +92,6 @@ You can still set these variables yourself using the `extra_args` configuration.
::: :::
## Next Steps ## Next Steps
* If you want to configure Atlantis further, read [Configuring Atlantis](configuring-atlantis.md) * If you want to configure Atlantis further, read [Configuring Atlantis](configuring-atlantis.md)
* If you're ready to use Atlantis, read [Using Atlantis](using-atlantis.md) * If you're ready to use Atlantis, read [Using Atlantis](using-atlantis.md)

62
runatlantis.io/docs/repo-level-atlantis-yaml.md
View File

@@ -1,15 +1,17 @@
# Repo Level atlantis.yaml Config # Repo Level atlantis.yaml Config
An `atlantis.yaml` file specified at the root of a Terraform repo allows you An `atlantis.yaml` file specified at the root of a Terraform repo allows you
to instruct Atlantis on the structure of your repo and set custom workflows. to instruct Atlantis on the structure of your repo and set custom workflows.
## Do I need an atlantis.yaml file? ## Do I need an atlantis.yaml file?
`atlantis.yaml` files are only required if you wish to customize some aspect of Atlantis. `atlantis.yaml` files are only required if you wish to customize some aspect of Atlantis.
The default Atlantis config works for many users without changes. The default Atlantis config works for many users without changes.
Read through the [use-cases](#use-cases) to determine if you need it. Read through the [use-cases](#use-cases) to determine if you need it.
## Enabling atlantis.yaml ## Enabling atlantis.yaml
By default, all repos are allowed to have an `atlantis.yaml` file, By default, all repos are allowed to have an `atlantis.yaml` file,
but some of the keys are restricted by default. but some of the keys are restricted by default.
@@ -18,7 +20,8 @@ You can enable `atlantis.yaml` to override restricted
keys by setting the `allowed_overrides` key there. See the [Server Side Repo Config](server-side-repo-config.md) for keys by setting the `allowed_overrides` key there. See the [Server Side Repo Config](server-side-repo-config.md) for
more details. more details.
**Notes** **Notes:**
* By default, repo root `atlantis.yaml` file is used. * By default, repo root `atlantis.yaml` file is used.
* You can change this behaviour by setting [Server Side Repo Config](server-side-repo-config.md) * You can change this behaviour by setting [Server Side Repo Config](server-side-repo-config.md)
@@ -146,7 +149,9 @@ grep -P 'backend[\s]+"s3"' **/*.tf |
``` ```
## Use Cases ## Use Cases
### Disabling Autoplanning ### Disabling Autoplanning
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -154,6 +159,7 @@ projects:
autoplan: autoplan:
enabled: false enabled: false
``` ```
This will stop Atlantis automatically running plan when `project1/` is updated This will stop Atlantis automatically running plan when `project1/` is updated
in a pull request. in a pull request.
@@ -177,7 +183,7 @@ Parallel plans and applies work across both multiple directories and multiple wo
Given the directory structure: Given the directory structure:
``` ```plain
. .
├── modules ├── modules
│   └── module1 │   └── module1
@@ -192,7 +198,6 @@ Given the directory structure:
If you want Atlantis to plan `project1/` whenever any `.tf` files under `module1/` change or any `.tf` or `.tfvars` files under `project1/` change you could use the following configuration: If you want Atlantis to plan `project1/` whenever any `.tf` files under `module1/` change or any `.tf` or `.tfvars` files under `project1/` change you could use the following configuration:
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -202,12 +207,14 @@ projects:
``` ```
Note: Note:
* `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) * `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file)
* The paths are relative to the project's directory. * The paths are relative to the project's directory.
* `when_modified` will be used by both automatic and manually run plans. * `when_modified` will be used by both automatic and manually run plans.
* `when_modified` will continue to work for manually run plans even when autoplan is disabled. * `when_modified` will continue to work for manually run plans even when autoplan is disabled.
### Supporting Terraform Workspaces ### Supporting Terraform Workspaces
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -216,34 +223,44 @@ projects:
- dir: project1 - dir: project1
workspace: production workspace: production
``` ```
With the above config, when Atlantis determines that the configuration for the `project1` dir has changed, With the above config, when Atlantis determines that the configuration for the `project1` dir has changed,
it will run plan for both the `staging` and `production` workspaces. it will run plan for both the `staging` and `production` workspaces.
If you want to `plan` or `apply` for a specific workspace you can use If you want to `plan` or `apply` for a specific workspace you can use
```
```shell
atlantis plan -w staging -d project1 atlantis plan -w staging -d project1
``` ```
and and
```
```shell
atlantis apply -w staging -d project1 atlantis apply -w staging -d project1
``` ```
### Using .tfvars files ### Using .tfvars files
See [Custom Workflow Use Cases: Using .tfvars files](custom-workflows.md#tfvars-files) See [Custom Workflow Use Cases: Using .tfvars files](custom-workflows.md#tfvars-files)
### Adding extra arguments to Terraform commands ### Adding extra arguments to Terraform commands
See [Custom Workflow Use Cases: Adding extra arguments to Terraform commands](custom-workflows.md#adding-extra-arguments-to-terraform-commands) See [Custom Workflow Use Cases: Adding extra arguments to Terraform commands](custom-workflows.md#adding-extra-arguments-to-terraform-commands)
### Custom init/plan/apply Commands ### Custom init/plan/apply Commands
See [Custom Workflow Use Cases: Custom init/plan/apply Commands](custom-workflows.md#custom-init-plan-apply-commands) See [Custom Workflow Use Cases: Custom init/plan/apply Commands](custom-workflows.md#custom-init-plan-apply-commands)
### Terragrunt ### Terragrunt
See [Custom Workflow Use Cases: Terragrunt](custom-workflows.md#terragrunt) See [Custom Workflow Use Cases: Terragrunt](custom-workflows.md#terragrunt)
### Running custom commands ### Running custom commands
See [Custom Workflow Use Cases: Running custom commands](custom-workflows.md#running-custom-commands) See [Custom Workflow Use Cases: Running custom commands](custom-workflows.md#running-custom-commands)
### Terraform Versions ### Terraform Versions
If you'd like to use a different version of Terraform than what is in Atlantis' If you'd like to use a different version of Terraform than what is in Atlantis'
`PATH` or is set by the `--default-tf-version` flag, then set the `terraform_version` key: `PATH` or is set by the `--default-tf-version` flag, then set the `terraform_version` key:
@@ -257,7 +274,9 @@ projects:
Atlantis will automatically download and use this version. Atlantis will automatically download and use this version.
### Requiring Approvals For Production ### Requiring Approvals For Production
In this example, we only want to require `apply` approvals for the `production` directory. In this example, we only want to require `apply` approvals for the `production` directory.
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -267,12 +286,14 @@ projects:
apply_requirements: [approved] apply_requirements: [approved]
import_requirements: [approved] import_requirements: [approved]
``` ```
:::warning :::warning
`plan_requirements`, `apply_requirements` and `import_requirements` are restricted keys so this repo will need to be configured `plan_requirements`, `apply_requirements` and `import_requirements` are restricted keys so this repo will need to be configured
to be allowed to set this key. See [Server-Side Repo Config Use Cases](server-side-repo-config.md#repos-can-set-their-own-apply-an-applicable-subcommand). to be allowed to set this key. See [Server-Side Repo Config Use Cases](server-side-repo-config.md#repos-can-set-their-own-apply-an-applicable-subcommand).
::: :::
### Order of planning/applying ### Order of planning/applying
```yaml ```yaml
version: 3 version: 3
abort_on_execution_order_fail: true abort_on_execution_order_fail: true
@@ -282,12 +303,13 @@ projects:
- dir: project2 - dir: project2
execution_order_group: 1 execution_order_group: 1
``` ```
With this config above, Atlantis runs planning/applying for project2 first, then for project1. With this config above, Atlantis runs planning/applying for project2 first, then for project1.
Several projects can have same `execution_order_group`. Any order in one group isn't guaranteed. Several projects can have same `execution_order_group`. Any order in one group isn't guaranteed.
`parallel_plan` and `parallel_apply` respect these order groups, so parallel planning/applying works `parallel_plan` and `parallel_apply` respect these order groups, so parallel planning/applying works
in each group one by one. in each group one by one.
If any plan/apply fails and `abort_on_execution_order_fail` is set to true on a repo level, all the If any plan/apply fails and `abort_on_execution_order_fail` is set to true on a repo level, all the
following groups will be aborted. For this example, if project2 fails then project1 will not run. following groups will be aborted. For this example, if project2 fails then project1 will not run.
Execution order groups are useful when you have dependencies between projects. However, they are only applicable in the case where Execution order groups are useful when you have dependencies between projects. However, they are only applicable in the case where
@@ -295,6 +317,7 @@ you initiate a global apply for all of your projects, i.e `atlantis apply`. If y
Thus, the `depends_on` key is more useful in this case. and can be used in conjunction with execution order groups. Thus, the `depends_on` key is more useful in this case. and can be used in conjunction with execution order groups.
The following configuration is an example of how to use execution order groups and depends_on together to enforce dependencies between projects. The following configuration is an example of how to use execution order groups and depends_on together to enforce dependencies between projects.
```yaml ```yaml
version: 3 version: 3
projects: projects:
@@ -322,6 +345,7 @@ projects:
workspace: production workspace: production
workflow: infra workflow: infra
``` ```
the `depends_on` feature will make sure that `production` is not applied before `staging` for example. the `depends_on` feature will make sure that `production` is not applied before `staging` for example.
::: tip ::: tip
@@ -330,11 +354,14 @@ What Happens if one or more project's dependencies are not applied?
If there's one or more projects in the dependency list which is not in applied status, users will see an error message like this: If there's one or more projects in the dependency list which is not in applied status, users will see an error message like this:
`Can't apply your project unless you apply its dependencies` `Can't apply your project unless you apply its dependencies`
::: :::
### Autodiscovery Config ### Autodiscovery Config
```yaml ```yaml
autodiscover: autodiscover:
mode: "auto" mode: "auto"
``` ```
The above is the default configuration for `autodiscover.mode`. When `autodiscover.mode` is auto, The above is the default configuration for `autodiscover.mode`. When `autodiscover.mode` is auto,
projects will be discovered only if the repo has no `projects` configured. projects will be discovered only if the repo has no `projects` configured.
@@ -342,6 +369,7 @@ projects will be discovered only if the repo has no `projects` configured.
autodiscover: autodiscover:
mode: "disabled" mode: "disabled"
``` ```
With the config above, Atlantis will never try to discover projects, even when there are no With the config above, Atlantis will never try to discover projects, even when there are no
`projects` configured. This is useful if dynamically generating Atlantis config in pre_workflow hooks. `projects` configured. This is useful if dynamically generating Atlantis config in pre_workflow hooks.
See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-generation). See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-generation).
@@ -350,6 +378,7 @@ See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-g
autodiscover: autodiscover:
mode: "enabled" mode: "enabled"
``` ```
With the config above, Atlantis will unconditionally try to discover projects based on modified_files, With the config above, Atlantis will unconditionally try to discover projects based on modified_files,
even when the directory of the project is missing from the configured `projects` in the repo configuration. even when the directory of the project is missing from the configured `projects` in the repo configuration.
If a discovered project has the same directory as a project which was manually configured in `projects`, If a discovered project has the same directory as a project which was manually configured in `projects`,
@@ -359,10 +388,13 @@ Use this feature when some projects require specific configuration in a repo wit
it's still desirable for Atlantis to plan/apply for projects not enumerated in the config. it's still desirable for Atlantis to plan/apply for projects not enumerated in the config.
### Custom Backend Config ### Custom Backend Config
See [Custom Workflow Use Cases: Custom Backend Config](custom-workflows.md#custom-backend-config) See [Custom Workflow Use Cases: Custom Backend Config](custom-workflows.md#custom-backend-config)
## Reference ## Reference
### Top-Level Keys ### Top-Level Keys
```yaml ```yaml
version: 3 version: 3
automerge: false automerge: false
@@ -371,6 +403,7 @@ projects:
workflows: workflows:
allowed_regexp_prefixes: allowed_regexp_prefixes:
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|-------------------------------|--------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------| |-------------------------------|--------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------|
| version | int | none | **yes** | This key is required and must be set to `3`. | | version | int | none | **yes** | This key is required and must be set to `3`. |
@@ -378,9 +411,10 @@ allowed_regexp_prefixes:
| delete_source_branch_on_merge | bool | `false` | no | Automatically deletes the source branch on merge. | | delete_source_branch_on_merge | bool | `false` | no | Automatically deletes the source branch on merge. |
| projects | array[[Project](repo-level-atlantis-yaml.md#project)] | `[]` | no | Lists the projects in this repo. | | projects | array[[Project](repo-level-atlantis-yaml.md#project)] | `[]` | no | Lists the projects in this repo. |
| workflows<br />*(restricted)* | map[string: [Workflow](custom-workflows.md#reference)] | `{}` | no | Custom workflows. | | workflows<br />*(restricted)* | map[string: [Workflow](custom-workflows.md#reference)] | `{}` | no | Custom workflows. |
| allowed_regexp_prefixes | array[string] | `[]` | no | Lists the allowed regexp prefixes to use when the [`--enable-regexp-cmd`](server-configuration.md#enable-regexp-cmd) flag is used. | | allowed_regexp_prefixes | array\[string\] | `[]` | no | Lists the allowed regexp prefixes to use when the [`--enable-regexp-cmd`](server-configuration.md#enable-regexp-cmd) flag is used. |
### Project ### Project
```yaml ```yaml
name: myname name: myname
branch: /mybranch/ branch: /mybranch/
@@ -410,9 +444,9 @@ workflow: myworkflow
| custom_policy_check | bool | `false` | no | Enable using policy check tools other than Conftest | | custom_policy_check | bool | `false` | no | Enable using policy check tools other than Conftest |
| autoplan | [Autoplan](#autoplan) | none | no | A custom autoplan configuration. If not specified, will use the autoplan config. See [Autoplanning](autoplanning.md). | | autoplan | [Autoplan](#autoplan) | none | no | A custom autoplan configuration. If not specified, will use the autoplan config. See [Autoplanning](autoplanning.md). |
| terraform_version | string | none | no | A specific Terraform version to use when running commands for this project. Must be [Semver compatible](https://semver.org/), ex. `v0.11.0`, `0.12.0-beta1`. | | terraform_version | string | none | no | A specific Terraform version to use when running commands for this project. Must be [Semver compatible](https://semver.org/), ex. `v0.11.0`, `0.12.0-beta1`. |
| plan_requirements<br />*(restricted)* | array[string] | none | no | Requirements that must be satisfied before `atlantis plan` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | plan_requirements<br />*(restricted)* | array\[string\] | none | no | Requirements that must be satisfied before `atlantis plan` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| apply_requirements<br />*(restricted)* | array[string] | none | no | Requirements that must be satisfied before `atlantis apply` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | apply_requirements<br />*(restricted)* | array\[string\] | none | no | Requirements that must be satisfied before `atlantis apply` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| import_requirements<br />*(restricted)* | array[string] | none | no | Requirements that must be satisfied before `atlantis import` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | import_requirements<br />*(restricted)* | array\[string\] | none | no | Requirements that must be satisfied before `atlantis import` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| workflow <br />*(restricted)* | string | none | no | A custom workflow. If not specified, Atlantis will use its default workflow. | | workflow <br />*(restricted)* | string | none | no | A custom workflow. If not specified, Atlantis will use its default workflow. |
::: tip ::: tip
@@ -422,11 +456,13 @@ Atlantis supports this but requires the `name` key to be specified. See [Custom
::: :::
### Autoplan ### Autoplan
```yaml ```yaml
enabled: true enabled: true
when_modified: ["*.tf", "terragrunt.hcl", ".terraform.lock.hcl"] when_modified: ["*.tf", "terragrunt.hcl", ".terraform.lock.hcl"]
``` ```
| Key | Type | Default | Required | Description | | Key | Type | Default | Required | Description |
|-----------------------|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-----------------------|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| enabled | boolean | `true` | no | Whether autoplanning is enabled for this project. | | enabled | boolean | `true` | no | Whether autoplanning is enabled for this project. |
| when_modified | array[string] | `["**/*.tf*"]` | no | Uses [.dockerignore](https://docs.docker.com/engine/reference/builder/#dockerignore-file) syntax. If any modified file in the pull request matches, this project will be planned. See [Autoplanning](autoplanning.md). Paths are relative to the project's dir. | | when_modified | array\[string\] | `["**/*.tf*"]` | no | Uses [.dockerignore](https://docs.docker.com/engine/reference/builder/#dockerignore-file) syntax. If any modified file in the pull request matches, this project will be planned. See [Autoplanning](autoplanning.md). Paths are relative to the project's dir. |

25
runatlantis.io/docs/requirements.md
View File

@@ -1,9 +1,10 @@
# Requirements # Requirements
Atlantis works with most Git hosts and Terraform setups. Read on to confirm Atlantis works with most Git hosts and Terraform setups. Read on to confirm
it works with yours. it works with yours.
## Git Host ## Git Host
Atlantis integrates with the following Git hosts: Atlantis integrates with the following Git hosts:
* GitHub (public, private or enterprise) * GitHub (public, private or enterprise)
@@ -14,6 +15,7 @@ Atlantis integrates with the following Git hosts:
* Azure DevOps * Azure DevOps
## Terraform State ## Terraform State
Atlantis supports all backend types **except for local state**. We don't support local state Atlantis supports all backend types **except for local state**. We don't support local state
because Atlantis does not have permanent storage and it doesn't commit the new because Atlantis does not have permanent storage and it doesn't commit the new
statefile back to version control. statefile back to version control.
@@ -24,17 +26,20 @@ storage from Terraform Cloud. This is fully supported by Atlantis.
::: :::
## Repository Structure ## Repository Structure
Atlantis supports any Terraform repository structure, for example: Atlantis supports any Terraform repository structure, for example:
### Single Terraform Project At Repo Root ### Single Terraform Project At Repo Root
```
```plain
. .
├── main.tf ├── main.tf
└── ... └── ...
``` ```
### Multiple Project Folders ### Multiple Project Folders
```
```plain
. .
├── project1 ├── project1
│   ├── main.tf │   ├── main.tf
@@ -45,7 +50,8 @@ Atlantis supports any Terraform repository structure, for example:
``` ```
### Modules ### Modules
```
```plain
. .
├── project1 ├── project1
│   ├── main.tf │   ├── main.tf
@@ -55,10 +61,12 @@ Atlantis supports any Terraform repository structure, for example:
   ├── main.tf    ├── main.tf
└── ... └── ...
``` ```
With modules, if you want `project1` automatically planned when `module1` is modified With modules, if you want `project1` automatically planned when `module1` is modified
you need to create an `atlantis.yaml` file. See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#configuring-planning) for more details. you need to create an `atlantis.yaml` file. See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#configuring-planning) for more details.
### Terraform Workspaces ### Terraform Workspaces
*See [Terraform's docs](https://developer.hashicorp.com/terraform/language/state/workspaces) if you are unfamiliar with workspaces.* *See [Terraform's docs](https://developer.hashicorp.com/terraform/language/state/workspaces) if you are unfamiliar with workspaces.*
If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an
@@ -66,24 +74,29 @@ If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an
(see [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#supporting-terraform-workspaces) for more details) (see [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#supporting-terraform-workspaces) for more details)
### .tfvars Files ### .tfvars Files
```
```plain
. .
├── production.tfvars ├── production.tfvars
│── staging.tfvars │── staging.tfvars
└── main.tf └── main.tf
``` ```
For Atlantis to be able to plan automatically with `.tfvars files`, you need to create For Atlantis to be able to plan automatically with `.tfvars files`, you need to create
an `atlantis.yaml` file to tell it to use `-var-file={YOUR_FILE}`. an `atlantis.yaml` file to tell it to use `-var-file={YOUR_FILE}`.
See [atlantis.yaml Use Cases](custom-workflows.md#tfvars-files) for more details. See [atlantis.yaml Use Cases](custom-workflows.md#tfvars-files) for more details.
### Multiple Repos ### Multiple Repos
Atlantis supports multiple repos as well–as long as there is a webhook configured Atlantis supports multiple repos as well–as long as there is a webhook configured
for each repo. for each repo.
## Terraform Versions ## Terraform Versions
Atlantis supports all Terraform versions (including 0.12) and can be configured Atlantis supports all Terraform versions (including 0.12) and can be configured
to use different versions for different repositories/projects. See [Terraform Versions](terraform-versions.md). to use different versions for different repositories/projects. See [Terraform Versions](terraform-versions.md).
## Next Steps ## Next Steps
* If your Terraform setup meets the Atlantis requirements, continue the installation * If your Terraform setup meets the Atlantis requirements, continue the installation
guide and set up your [Git Host Access Credentials](access-credentials.md) guide and set up your [Git Host Access Credentials](access-credentials.md)

20
runatlantis.io/docs/security.md
View File

@@ -1,12 +1,16 @@
# Security # Security
## Exploits ## Exploits
Because you usually run Atlantis on a server with credentials that allow access to your infrastructure it's important that you deploy Atlantis securely. Because you usually run Atlantis on a server with credentials that allow access to your infrastructure it's important that you deploy Atlantis securely.
Atlantis could be exploited by Atlantis could be exploited by
* An attacker submitting a pull request that contains a malicious Terraform file that * An attacker submitting a pull request that contains a malicious Terraform file that
uses a malicious provider or an [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source) uses a malicious provider or an [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source)
that Atlantis then runs `terraform plan` on (which it does automatically unless you've turned off automatic plans). that Atlantis then runs `terraform plan` on (which it does automatically unless you've turned off automatic plans).
* Running `terraform apply` on a malicious Terraform file with [local-exec](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec) * Running `terraform apply` on a malicious Terraform file with [local-exec](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec)
```tf ```tf
resource "null_resource" "null" { resource "null_resource" "null" {
provisioner "local-exec" { provisioner "local-exec" {
@@ -14,10 +18,12 @@ Atlantis could be exploited by
} }
} }
``` ```
* Running malicious custom build commands specified in an `atlantis.yaml` file. Atlantis uses the `atlantis.yaml` file from the pull request branch, **not** `main`. * Running malicious custom build commands specified in an `atlantis.yaml` file. Atlantis uses the `atlantis.yaml` file from the pull request branch, **not** `main`.
* Someone adding `atlantis plan/apply` comments on your valid pull requests causing terraform to run when you don't want it to. * Someone adding `atlantis plan/apply` comments on your valid pull requests causing terraform to run when you don't want it to.
## Bitbucket Cloud (bitbucket.org) ## Bitbucket Cloud (bitbucket.org)
::: danger ::: danger
Bitbucket Cloud does not support webhook secrets. This could allow attackers to spoof requests from Bitbucket. Ensure you are allowing only Bitbucket IPs. Bitbucket Cloud does not support webhook secrets. This could allow attackers to spoof requests from Bitbucket. Ensure you are allowing only Bitbucket IPs.
::: :::
@@ -32,16 +38,21 @@ To prevent this, allowlist [Bitbucket's IP addresses](https://confluence.atlassi
(see Outbound IPv4 addresses). (see Outbound IPv4 addresses).
## Mitigations ## Mitigations
### Don't Use On Public Repos ### Don't Use On Public Repos
Because anyone can comment on public pull requests, even with all the security mitigations available, it's still dangerous to run Atlantis on public repos without proper configuration of the security settings. Because anyone can comment on public pull requests, even with all the security mitigations available, it's still dangerous to run Atlantis on public repos without proper configuration of the security settings.
### Don't Use `--allow-fork-prs` ### Don't Use `--allow-fork-prs`
If you're running on a public repo (which isn't recommended, see above) you shouldn't set `--allow-fork-prs` (defaults to false) If you're running on a public repo (which isn't recommended, see above) you shouldn't set `--allow-fork-prs` (defaults to false)
because anyone can open up a pull request from their fork to your repo. because anyone can open up a pull request from their fork to your repo.
### `--repo-allowlist` ### `--repo-allowlist`
Atlantis requires you to specify a allowlist of repositories it will accept webhooks from via the `--repo-allowlist` flag. Atlantis requires you to specify a allowlist of repositories it will accept webhooks from via the `--repo-allowlist` flag.
For example: For example:
* Specific repositories: `--repo-allowlist=github.com/runatlantis/atlantis,github.com/runatlantis/atlantis-tests` * Specific repositories: `--repo-allowlist=github.com/runatlantis/atlantis,github.com/runatlantis/atlantis-tests`
* Your whole organization: `--repo-allowlist=github.com/runatlantis/*` * Your whole organization: `--repo-allowlist=github.com/runatlantis/*`
* Every repository in your GitHub Enterprise install: `--repo-allowlist=github.yourcompany.com/*` * Every repository in your GitHub Enterprise install: `--repo-allowlist=github.yourcompany.com/*`
@@ -51,12 +62,14 @@ For example:
This flag ensures your Atlantis install isn't being used with repositories you don't control. See `atlantis server --help` for more details. This flag ensures your Atlantis install isn't being used with repositories you don't control. See `atlantis server --help` for more details.
### Protect Terraform Planning ### Protect Terraform Planning
If attackers submitting pull requests with malicious Terraform code is in your threat model If attackers submitting pull requests with malicious Terraform code is in your threat model
then you must be aware that `terraform apply` approvals are not enough. It is possible then you must be aware that `terraform apply` approvals are not enough. It is possible
to run malicious code in a `terraform plan` using the [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source) to run malicious code in a `terraform plan` using the [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source)
or by specifying a malicious provider. This code could then exfiltrate your credentials. or by specifying a malicious provider. This code could then exfiltrate your credentials.
To prevent this, you could: To prevent this, you could:
1. Bake providers into the Atlantis image or host and deny egress in production. 1. Bake providers into the Atlantis image or host and deny egress in production.
1. Implement the provider registry protocol internally and deny public egress, that way you control who has write access to the registry. 1. Implement the provider registry protocol internally and deny public egress, that way you control who has write access to the registry.
1. Modify your [server-side repo configuration](server-side-repo-config.md)'s `plan` step to validate against the 1. Modify your [server-side repo configuration](server-side-repo-config.md)'s `plan` step to validate against the
@@ -64,6 +77,7 @@ To prevent this, you could:
requiring a "thumbs-up" on the PR before allowing the `plan` to continue. Conftest could be of use here. requiring a "thumbs-up" on the PR before allowing the `plan` to continue. Conftest could be of use here.
### `--var-file-allowlist` ### `--var-file-allowlist`
The files on your Atlantis install may be accessible as [variable definition files](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files) The files on your Atlantis install may be accessible as [variable definition files](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files)
from pull requests by adding from pull requests by adding
`atlantis plan -- -var-file=/path/to/file` comments. To mitigate this security risk, Atlantis has limited such access `atlantis plan -- -var-file=/path/to/file` comments. To mitigate this security risk, Atlantis has limited such access
@@ -71,6 +85,7 @@ only to the files allowlisted by the `--var-file-allowlist` flag. If this argume
Atlantis' data directory. Atlantis' data directory.
### Webhook Secrets ### Webhook Secrets
Atlantis should be run with Webhook secrets set via the `$ATLANTIS_GH_WEBHOOK_SECRET`/`$ATLANTIS_GITLAB_WEBHOOK_SECRET` environment variables. Atlantis should be run with Webhook secrets set via the `$ATLANTIS_GH_WEBHOOK_SECRET`/`$ATLANTIS_GITLAB_WEBHOOK_SECRET` environment variables.
Even with the `--repo-allowlist` flag set, without a webhook secret, attackers could make requests to Atlantis posing as a repository that is allowlisted. Even with the `--repo-allowlist` flag set, without a webhook secret, attackers could make requests to Atlantis posing as a repository that is allowlisted.
Webhook secrets ensure that the webhook requests are actually coming from your VCS provider (GitHub or GitLab). Webhook secrets ensure that the webhook requests are actually coming from your VCS provider (GitHub or GitLab).
@@ -80,17 +95,20 @@ If you are using Azure DevOps, instead of webhook secrets add a [basic username
::: :::
### Azure DevOps Basic Authentication ### Azure DevOps Basic Authentication
Azure DevOps supports sending a basic authentication header in all webhook events. This requires using an HTTPS URL for your webhook location. Azure DevOps supports sending a basic authentication header in all webhook events. This requires using an HTTPS URL for your webhook location.
### SSL/HTTPS ### SSL/HTTPS
If you're using webhook secrets but your traffic is over HTTP then the webhook secrets If you're using webhook secrets but your traffic is over HTTP then the webhook secrets
could be stolen. Enable SSL/HTTPS using the `--ssl-cert-file` and `--ssl-key-file` could be stolen. Enable SSL/HTTPS using the `--ssl-cert-file` and `--ssl-key-file`
flags. flags.
### Enable Authentication on Atlantis Web Server ### Enable Authentication on Atlantis Web Server
It is very recommended to enable authentication in the web service. Enable BasicAuth using the `--web-basic-auth=true` and setup a username and a password using `--web-username=yourUsername` and `--web-password=yourPassword` flags. It is very recommended to enable authentication in the web service. Enable BasicAuth using the `--web-basic-auth=true` and setup a username and a password using `--web-username=yourUsername` and `--web-password=yourPassword` flags.
You can also pass these as environment variables `ATLANTIS_WEB_BASIC_AUTH=true` `ATLANTIS_WEB_USERNAME=yourUsername` and `ATLANTIS_WEB_PASSWORD=yourPassword`. You can also pass these as environment variables `ATLANTIS_WEB_BASIC_AUTH=true` `ATLANTIS_WEB_USERNAME=yourUsername` and `ATLANTIS_WEB_PASSWORD=yourPassword`.
:::tip Tip :::tip Tip
We do encourage the usage of complex passwords in order to prevent basic bruteforcing attacks. We do encourage the usage of complex passwords in order to prevent basic bruteforcing attacks.

309
runatlantis.io/docs/server-configuration.md
View File

File diff suppressed because it is too large Load Diff

3
runatlantis.io/docs/server-side-repo-config.md
View File

@@ -5,7 +5,6 @@ A Server-Side Config file is used for more groups of server config that can't re
One such usecase is to control per-repo behaviour One such usecase is to control per-repo behaviour
and what users can do in repo-level `atlantis.yaml` files. and what users can do in repo-level `atlantis.yaml` files.
## Do I Need A Server-Side Config File? ## Do I Need A Server-Side Config File?
You do not need a server-side repo config file unless you want to customize You do not need a server-side repo config file unless you want to customize
@@ -525,7 +524,7 @@ If you set a workflow with the key `default`, it will override this.
| branch | string | none | no | An regex matching pull requests by base branch (the branch the pull request is getting merged into). By default, all branches are matched | | branch | string | none | no | An regex matching pull requests by base branch (the branch the pull request is getting merged into). By default, all branches are matched |
| repo_config_file | string | none | no | Repo config file path in this repo. By default, use `atlantis.yaml` which is located on repository root. When multiple atlantis servers work with the same repo, please set different file names. | | repo_config_file | string | none | no | Repo config file path in this repo. By default, use `atlantis.yaml` which is located on repository root. When multiple atlantis servers work with the same repo, please set different file names. |
| workflow | string | none | no | A custom workflow. | | workflow | string | none | no | A custom workflow. |
| plan_requirements | []string | none | no | Requirements that must be satisfied before `atlantis plan` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | | plan_requirements | []string | none | no | Requirements that must be satisfied before `atlantis plan` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| apply_requirements | []string | none | no | Requirements that must be satisfied before `atlantis apply` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | apply_requirements | []string | none | no | Requirements that must be satisfied before `atlantis apply` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| import_requirements | []string | none | no | Requirements that must be satisfied before `atlantis import` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. | | import_requirements | []string | none | no | Requirements that must be satisfied before `atlantis import` can be run. Currently the only supported requirements are `approved`, `mergeable`, and `undiverged`. See [Command Requirements](command-requirements.md) for more details. |
| allowed_overrides | []string | none | no | A list of restricted keys that `atlantis.yaml` files can override. The only supported keys are `apply_requirements`, `workflow`, `delete_source_branch_on_merge`,`repo_locking`, and `custom_policy_check` | | allowed_overrides | []string | none | no | A list of restricted keys that `atlantis.yaml` files can override. The only supported keys are `apply_requirements`, `workflow`, `delete_source_branch_on_merge`,`repo_locking`, and `custom_policy_check` |

4
runatlantis.io/docs/stats.md
View File

@@ -14,17 +14,14 @@ Metrics are configured through the [Server Side Config](server-side-repo-config.
Assuming metrics are exposed from the endpoint `/metrics` from the [metrics](server-side-repo-config.md#metrics) server side config e.g. Assuming metrics are exposed from the endpoint `/metrics` from the [metrics](server-side-repo-config.md#metrics) server side config e.g.
```yaml ```yaml
metrics: metrics:
prometheus: prometheus:
endpoint: "/metrics" endpoint: "/metrics"
``` ```
To see all the metrics exposed from atlantis service, make a GET request to the `/metrics` endpoint. To see all the metrics exposed from atlantis service, make a GET request to the `/metrics` endpoint.
```bash ```bash
curl localhost:4141/metrics curl localhost:4141/metrics
# HELP atlantis_cmd_autoplan_builder_execution_error atlantis_cmd_autoplan_builder_execution_error counter # HELP atlantis_cmd_autoplan_builder_execution_error atlantis_cmd_autoplan_builder_execution_error counter
@@ -47,7 +44,6 @@ atlantis_cmd_autoplan_builder_execution_time_count 10
..... .....
``` ```
::: tip NOTE ::: tip NOTE
The output shown above is trimmed, since with every new version release this metric set will need to be updated accordingly as there may be a case if some metrics are added/modified/deprecated, so the output shown above just gives a brief idea of how these metrics look like and rest can be explored. The output shown above is trimmed, since with every new version release this metric set will need to be updated accordingly as there may be a case if some metrics are added/modified/deprecated, so the output shown above just gives a brief idea of how these metrics look like and rest can be explored.
::: :::

1
runatlantis.io/docs/streaming-logs.md
View File

@@ -20,4 +20,3 @@ This will link to the atlantis UI which provides real-time logging in addition t
::: warning ::: warning
As of now the logs are currently stored in memory and cleared when a given pull request is closed, so this link shouldn't be persisted anywhere. As of now the logs are currently stored in memory and cleared when a given pull request is closed, so this link shouldn't be persisted anywhere.
::: :::

16
runatlantis.io/docs/terraform-cloud.md
View File

@@ -6,6 +6,7 @@ and Private Terraform Enterprise was renamed Terraform Enterprise.
::: :::
Atlantis integrates seamlessly with Terraform Cloud and Terraform Enterprise, whether you're using: Atlantis integrates seamlessly with Terraform Cloud and Terraform Enterprise, whether you're using:
* [Free Remote State Management](https://app.terraform.io) * [Free Remote State Management](https://app.terraform.io)
* Terraform Cloud Paid Tiers * Terraform Cloud Paid Tiers
* A Private Installation of Terraform Enterprise * A Private Installation of Terraform Enterprise
@@ -13,7 +14,9 @@ Atlantis integrates seamlessly with Terraform Cloud and Terraform Enterprise, wh
Read the docs below :point_down: depending on your use-case. Read the docs below :point_down: depending on your use-case.
## Using Atlantis With Free Remote State Storage ## Using Atlantis With Free Remote State Storage
To use Atlantis with Free Remote State Storage, you need to: To use Atlantis with Free Remote State Storage, you need to:
1. Migrate your state to Terraform Cloud. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate) 1. Migrate your state to Terraform Cloud. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate)
1. Update any projects that are referencing the state you migrated to use the new location 1. Update any projects that are referencing the state you migrated to use the new location
1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token) 1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token)
@@ -23,6 +26,7 @@ That's it! Atlantis will run as normal and your state will be stored in Terrafor
Cloud. Cloud.
## Using Atlantis With Terraform Cloud Remote Operations or Terraform Enterprise ## Using Atlantis With Terraform Cloud Remote Operations or Terraform Enterprise
Atlantis integrates with the full version of Terraform Cloud and Terraform Enterprise Atlantis integrates with the full version of Terraform Cloud and Terraform Enterprise
via the [remote backend](https://developer.hashicorp.com/terraform/language/settings/backends/remote). via the [remote backend](https://developer.hashicorp.com/terraform/language/settings/backends/remote).
@@ -30,7 +34,9 @@ Atlantis will run `terraform` commands as usual, however those commands will
actually be executed *remotely* in Terraform Cloud or Terraform Enterprise. actually be executed *remotely* in Terraform Cloud or Terraform Enterprise.
### Why? ### Why?
Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to features like: Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to features like:
* Real-time streaming output * Real-time streaming output
* Ability to cancel in-progress commands * Ability to cancel in-progress commands
* Secret variables * Secret variables
@@ -39,28 +45,34 @@ Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to
**Without** having to change your pull request workflow. **Without** having to change your pull request workflow.
### Getting Started ### Getting Started
To use Atlantis with Terraform Cloud Remote Operations or Terraform Enterprise, you need to: To use Atlantis with Terraform Cloud Remote Operations or Terraform Enterprise, you need to:
1. Migrate your state to Terraform Cloud/Enterprise. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate) 1. Migrate your state to Terraform Cloud/Enterprise. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate)
1. Update any projects that are referencing the state you migrated to use the new location 1. Update any projects that are referencing the state you migrated to use the new location
1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token) 1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token)
1. [Pass the token to Atlantis](#passing-the-token-to-atlantis) 1. [Pass the token to Atlantis](#passing-the-token-to-atlantis)
## Generating a Terraform Cloud/Enterprise Token ## Generating a Terraform Cloud/Enterprise Token
Atlantis needs a Terraform Cloud/Enterprise Token that it will use to access the API. Atlantis needs a Terraform Cloud/Enterprise Token that it will use to access the API.
Using a **Team Token is recommended**, however you can also use a User Token. Using a **Team Token is recommended**, however you can also use a User Token.
### Team Token ### Team Token
To generate a team token, click on **Settings** in the top bar, then **Teams** in To generate a team token, click on **Settings** in the top bar, then **Teams** in
the sidebar. the sidebar.
Choose an existing team or create a new one. Choose an existing team or create a new one.
Enable the **Manage Workspaces** permission, then scroll down to **Team API Token**. Enable the **Manage Workspaces** permission, then scroll down to **Team API Token**.
### User Token ### User Token
To generate a user token, click on your avatar, then **User Settings**, then To generate a user token, click on your avatar, then **User Settings**, then
**Tokens** in the sidebar. **Tokens** in the sidebar.
Ensure the **Manage Workspaces** permission is enabled for this user's team. Ensure the **Manage Workspaces** permission is enabled for this user's team.
## Passing The Token To Atlantis ## Passing The Token To Atlantis
The token can be passed to Atlantis via the `ATLANTIS_TFE_TOKEN` environment variable. The token can be passed to Atlantis via the `ATLANTIS_TFE_TOKEN` environment variable.
You can also use the `--tfe-token` flag, however your token would then be easily You can also use the `--tfe-token` flag, however your token would then be easily
@@ -87,12 +99,14 @@ Under the hood, Atlantis is generating a `~/.terraformrc` file.
If you already had a `~/.terraformrc` file where Atlantis is running, If you already had a `~/.terraformrc` file where Atlantis is running,
then you'll need to manually then you'll need to manually
add the credentials block to that file: add the credentials block to that file:
```
```hcl
... ...
credentials "app.terraform.io" { credentials "app.terraform.io" {
token = "xxxx" token = "xxxx"
} }
``` ```
instead of using the `ATLANTIS_TFE_TOKEN` environment variable, since Atlantis instead of using the `ATLANTIS_TFE_TOKEN` environment variable, since Atlantis
won't overwrite your `.terraformrc` file. won't overwrite your `.terraformrc` file.
::: :::

21
runatlantis.io/docs/terraform-versions.md
View File

@@ -4,42 +4,55 @@ You can customize which version of Terraform Atlantis defaults to by setting
the `--default-tf-version` flag (ex. `--default-tf-version=v1.3.7`). the `--default-tf-version` flag (ex. `--default-tf-version=v1.3.7`).
## Via `atlantis.yaml` ## Via `atlantis.yaml`
If you wish to use a different version than the default for a specific repo or project, you need If you wish to use a different version than the default for a specific repo or project, you need
to create an `atlantis.yaml` file and set the `terraform_version` key: to create an `atlantis.yaml` file and set the `terraform_version` key:
```yaml ```yaml
version: 3 version: 3
projects: projects:
- dir: . - dir: .
terraform_version: v1.1.5 terraform_version: v1.1.5
``` ```
See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#terraform-versions) for more details. See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#terraform-versions) for more details.
## Via terraform config ## Via terraform config
Alternatively, one can use the terraform configuration block's `required_version` key to specify an exact version (`x.y.z` or `= x.y.z`), or as of [atlantis v0.21.0](https://github.com/runatlantis/atlantis/releases/tag/v0.21.0), a comparison or pessimistic [version constraint](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#version-constraint-syntax): Alternatively, one can use the terraform configuration block's `required_version` key to specify an exact version (`x.y.z` or `= x.y.z`), or as of [atlantis v0.21.0](https://github.com/runatlantis/atlantis/releases/tag/v0.21.0), a comparison or pessimistic [version constraint](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#version-constraint-syntax):
#### Exactly version 1.2.9
### Exactly version 1.2.9
```tf ```tf
terraform { terraform {
required_version = "= 1.2.9" required_version = "= 1.2.9"
} }
``` ```
#### Any patch/tiny version of minor version 1.2 (1.2.z)
### Any patch/tiny version of minor version 1.2 (1.2.z)
```tf ```tf
terraform { terraform {
required_version = "~> 1.2.0" required_version = "~> 1.2.0"
} }
``` ```
#### Any minor version of major version 1 (1.y.z)
### Any minor version of major version 1 (1.y.z)
```tf ```tf
terraform { terraform {
required_version = "~> 1.2" required_version = "~> 1.2"
} }
``` ```
#### Any version that is at least 1.2.0
### Any version that is at least 1.2.0
```tf ```tf
terraform { terraform {
required_version = ">= 1.2.0" required_version = ">= 1.2.0"
} }
``` ```
See [Terraform `required_version`](https://developer.hashicorp.com/terraform/language/settings#specifying-a-required-terraform-version) for reference. See [Terraform `required_version`](https://developer.hashicorp.com/terraform/language/settings#specifying-a-required-terraform-version) for reference.
::: tip NOTE ::: tip NOTE

17
runatlantis.io/docs/troubleshooting-https.md
View File

@@ -3,17 +3,18 @@
When using a self-signed certificate for Atlantis (with flags `--ssl-cert-file` and `--ssl-key-file`), When using a self-signed certificate for Atlantis (with flags `--ssl-cert-file` and `--ssl-key-file`),
there are a few considerations. there are a few considerations.
Atlantis uses the web server from the standard Go library, Atlantis uses the web server from the standard Go library,
the method name is [ListenAndServeTLS](https://pkg.go.dev/net/http#ListenAndServeTLS). the method name is [ListenAndServeTLS](https://pkg.go.dev/net/http#ListenAndServeTLS).
`ListenAndServeTLS` acts identically to [ListenAndServe](https://pkg.go.dev/net/http#ListenAndServe), `ListenAndServeTLS` acts identically to [ListenAndServe](https://pkg.go.dev/net/http#ListenAndServe),
except that it expects HTTPS connections. except that it expects HTTPS connections.
Additionally, files containing a certificate and matching private key for the server must be provided. Additionally, files containing a certificate and matching private key for the server must be provided.
If the certificate is signed by a certificate authority, If the certificate is signed by a certificate authority,
the file passed to `--ssl-cert-file` should be the concatenation of the server's certificate, any intermediates, and the CA's certificate. the file passed to `--ssl-cert-file` should be the concatenation of the server's certificate, any intermediates, and the CA's certificate.
If you have this error when specifying a TLS cert with a key: If you have this error when specifying a TLS cert with a key:
```
```plain
[ERROR] server.go:413 server: Tls: private key does not match public key [ERROR] server.go:413 server: Tls: private key does not match public key
``` ```
@@ -23,5 +24,3 @@ A good example is shown at [Seth Vargo terraform implementation of atlantis-on-g
For Go specific TLS resources have a look at the repository by [denji called golang-tls](https://github.com/denji/golang-tls). For Go specific TLS resources have a look at the repository by [denji called golang-tls](https://github.com/denji/golang-tls).
For a complete explanation on PKI, read this [article](https://smallstep.com/blog/everything-pki.html). For a complete explanation on PKI, read this [article](https://smallstep.com/blog/everything-pki.html).

29
runatlantis.io/docs/upgrading-atlantis-yaml.md
View File

@@ -1,6 +1,7 @@
# Upgrading atlantis.yaml # Upgrading atlantis.yaml
## Upgrading From v2 To v3 ## Upgrading From v2 To v3
Atlantis version `v0.7.0` introduced a new version 3 of `atlantis.yaml`. Atlantis version `v0.7.0` introduced a new version 3 of `atlantis.yaml`.
**If you're not using [custom `run` steps](custom-workflows.md#custom-run-command), **If you're not using [custom `run` steps](custom-workflows.md#custom-run-command),
@@ -10,6 +11,7 @@ Atlantis version `v0.7.0` introduced a new version 3 of `atlantis.yaml`.
if you don't wish to do so. if you don't wish to do so.
The only change from v2 to v3 is that we're parsing custom `run` steps differently. The only change from v2 to v3 is that we're parsing custom `run` steps differently.
```yaml ```yaml
# atlantis.yaml # atlantis.yaml
workflows: workflows:
@@ -18,33 +20,38 @@ workflows:
steps: steps:
- run: my custom command - run: my custom command
``` ```
<center><i>An example workflow using a custom run step</i></center> <center><i>An example workflow using a custom run step</i></center>
Previously, we used a library that would parse the custom step prior to running Previously, we used a library that would parse the custom step prior to running
it. Now, we just run the step directly. This will only affect your steps if they were using shell escaping of some sort. it. Now, we just run the step directly. This will only affect your steps if they were using shell escaping of some sort.
For example, if your step was previously: For example, if your step was previously:
```yaml ```yaml
# version: 2 # version: 2
- run: "printf \'print me\'" - run: "printf \'print me\'"
``` ```
You can now write this in version 3 as: You can now write this in version 3 as:
```yaml ```yaml
# version: 3 # version: 3
- run: "printf 'print me'" - run: "printf 'print me'"
``` ```
## Upgrading From V1 To V3 ## Upgrading From V1 To V3
If you are upgrading from an **old** Atlantis version `<=v0.3.10` (from before July 4, 2018) If you are upgrading from an **old** Atlantis version `<=v0.3.10` (from before July 4, 2018)
you'll need to follow the following steps. you'll need to follow the following steps.
### Single atlantis.yaml ### Single atlantis.yaml
If you had multiple `atlantis.yaml` files per directory then you'll need to If you had multiple `atlantis.yaml` files per directory then you'll need to
consolidate them into a single `atlantis.yaml` file at the root of the repo. consolidate them into a single `atlantis.yaml` file at the root of the repo.
For example, if you had a directory structure: For example, if you had a directory structure:
```
```plain
. .
├── project1 ├── project1
│ └── atlantis.yaml │ └── atlantis.yaml
@@ -53,7 +60,8 @@ For example, if you had a directory structure:
``` ```
Then your new structure would look like: Then your new structure would look like:
```
```plain
. .
├── atlantis.yaml ├── atlantis.yaml
├── project1 ├── project1
@@ -61,6 +69,7 @@ Then your new structure would look like:
``` ```
And your `atlantis.yaml` would look something like: And your `atlantis.yaml` would look something like:
```yaml ```yaml
version: 2 version: 2
projects: projects:
@@ -80,13 +89,16 @@ workflows:
We will talk more about `workflows` below. We will talk more about `workflows` below.
### Terraform Version ### Terraform Version
The `terraform_version` key moved from being a top-level key to being per `project` The `terraform_version` key moved from being a top-level key to being per `project`
so if before your `atlantis.yaml` was in directory `mydir` and looked like: so if before your `atlantis.yaml` was in directory `mydir` and looked like:
```yaml ```yaml
terraform_version: 0.11.0 terraform_version: 0.11.0
``` ```
Then your new config would be: Then your new config would be:
```yaml ```yaml
version: 2 version: 2
projects: projects:
@@ -95,9 +107,11 @@ projects:
``` ```
### Workflows ### Workflows
Workflows are the new way to set all `pre_*`, `post_*` and `extra_arguments`. Workflows are the new way to set all `pre_*`, `post_*` and `extra_arguments`.
Each `project` can have a custom workflow via the `workflow` key. Each `project` can have a custom workflow via the `workflow` key.
```yaml ```yaml
version: 2 version: 2
projects: projects:
@@ -106,6 +120,7 @@ projects:
``` ```
Workflows are defined as a top-level key: Workflows are defined as a top-level key:
```yaml ```yaml
version: 2 version: 2
projects: projects:
@@ -118,6 +133,7 @@ workflows:
To start with, determine whether you're customizing commands that happen during To start with, determine whether you're customizing commands that happen during
`plan` or `apply`. You then set that key under the workflow's name: `plan` or `apply`. You then set that key under the workflow's name:
```yaml ```yaml
... ...
workflows: workflows:
@@ -133,6 +149,7 @@ workflows:
If you're not customizing a specific stage then you can omit that key. For example If you're not customizing a specific stage then you can omit that key. For example
if you're only customizing the commands that happen during `plan` then your config if you're only customizing the commands that happen during `plan` then your config
will look like: will look like:
```yaml ```yaml
... ...
workflows: workflows:
@@ -143,7 +160,9 @@ workflows:
``` ```
#### Extra Arguments #### Extra Arguments
`extra_arguments` is now specified as follows. Given a previous config: `extra_arguments` is now specified as follows. Given a previous config:
```yaml ```yaml
extra_arguments: extra_arguments:
- command_name: init - command_name: init
@@ -158,6 +177,7 @@ extra_arguments:
``` ```
Your config would now look like: Your config would now look like:
```yaml ```yaml
... ...
workflows: workflows:
@@ -174,8 +194,8 @@ workflows:
extra_args: ["-lock=false"] extra_args: ["-lock=false"]
``` ```
#### Pre/Post Commands #### Pre/Post Commands
Instead of using `pre_*` or `post_*`, you now can insert your custom commands Instead of using `pre_*` or `post_*`, you now can insert your custom commands
before/after the built-in commands. Given a previous config: before/after the built-in commands. Given a previous config:
@@ -202,6 +222,7 @@ post_apply:
``` ```
Your config would now look like: Your config would now look like:
```yaml ```yaml
... ...
workflows: workflows:

61
runatlantis.io/docs/using-atlantis.md
View File

@@ -5,6 +5,7 @@ Atlantis triggers commands via pull request comments.
::: tip ::: tip
You can use following executable names. You can use following executable names.
* `atlantis help` * `atlantis help`
* `atlantis` is executable name. You can configure by [Executable Name](server-configuration.md#executable-name). * `atlantis` is executable name. You can configure by [Executable Name](server-configuration.md#executable-name).
* `run help` * `run help`
@@ -16,32 +17,44 @@ You can use following executable names.
Currently, Atlantis supports the following commands. Currently, Atlantis supports the following commands.
--- ---
## atlantis help ## atlantis help
```bash ```bash
atlantis help atlantis help
``` ```
### Explanation ### Explanation
View help View help
--- ---
## atlantis version ## atlantis version
```bash ```bash
atlantis version atlantis version
``` ```
### Explanation ### Explanation
Print the output of 'terraform version'. Print the output of 'terraform version'.
--- ---
## atlantis plan ## atlantis plan
```bash ```bash
atlantis plan [options] -- [terraform plan flags] atlantis plan [options] -- [terraform plan flags]
``` ```
### Explanation ### Explanation
Runs `terraform plan` on the pull request's branch. You may wish to re-run plan after Atlantis has already done Runs `terraform plan` on the pull request's branch. You may wish to re-run plan after Atlantis has already done
so if you've changed some resources manually. so if you've changed some resources manually.
### Examples ### Examples
```bash ```bash
# Runs plan for any projects that Atlantis thinks were modified. # Runs plan for any projects that Atlantis thinks were modified.
# If an `atlantis.yaml` file is specified, runs plan on the projects that # If an `atlantis.yaml` file is specified, runs plan on the projects that
@@ -59,8 +72,9 @@ atlantis plan -w staging
``` ```
### Options ### Options
* `-d directory` Which directory to run plan in relative to root of repo. Use `.` for root. * `-d directory` Which directory to run plan in relative to root of repo. Use `.` for root.
* Ex. `atlantis plan -d child/dir` * Ex. `atlantis plan -d child/dir`
* `-p project` Which project to run plan for. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w` because the project defines this already. * `-p project` Which project to run plan for. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w` because the project defines this already.
* `-w workspace` Switch to this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces) before planning. Defaults to `default`. Ignore this if Terraform workspaces are unused. * `-w workspace` Switch to this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces) before planning. Defaults to `default`. Ignore this if Terraform workspaces are unused.
* `--verbose` Append Atlantis log to comment. * `--verbose` Append Atlantis log to comment.
@@ -73,30 +87,38 @@ A `atlantis plan` (without flags), like autoplans, discards all plans previously
If `terraform plan` requires additional arguments, like `-target=resource` or `-var 'foo=bar'` or `-var-file myfile.tfvars` If `terraform plan` requires additional arguments, like `-target=resource` or `-var 'foo=bar'` or `-var-file myfile.tfvars`
you can append them to the end of the comment after `--`, ex. you can append them to the end of the comment after `--`, ex.
```
```shell
atlantis plan -d dir -- -var foo='bar' atlantis plan -d dir -- -var foo='bar'
``` ```
If you always need to append a certain flag, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). If you always need to append a certain flag, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands).
### Using the -destroy Flag ### Using the -destroy Flag
#### Example #### Example
To perform a destructive plan that will destroy resources you can use the `-destroy` flag like this: To perform a destructive plan that will destroy resources you can use the `-destroy` flag like this:
```bash ```bash
atlantis plan -- -destroy atlantis plan -- -destroy
atlantis plan -d dir -- -destroy atlantis plan -d dir -- -destroy
``` ```
::: warning NOTE
::: warning NOTE
The `-destroy` flag generates a destroy plan, If this plan is applied it can result in data loss or service disruptions. Ensure that you have thoroughly reviewed your Terraform configuration and intend to remove the specified resources before using this flag. The `-destroy` flag generates a destroy plan, If this plan is applied it can result in data loss or service disruptions. Ensure that you have thoroughly reviewed your Terraform configuration and intend to remove the specified resources before using this flag.
::: :::
--- ---
## atlantis apply ## atlantis apply
```bash ```bash
atlantis apply [options] -- [terraform apply flags] atlantis apply [options] -- [terraform apply flags]
``` ```
### Explanation ### Explanation
Runs `terraform apply` for the plan that matches the directory/project/workspace. Runs `terraform apply` for the plan that matches the directory/project/workspace.
::: tip ::: tip
@@ -105,8 +127,8 @@ This includes all projects that have been planned manually with `atlantis plan`
For Atlantis commands to work, Atlantis needs to know the location where the plan file is. For that, you can use $PLANFILE which will contain the path of the plan file to be used in your custom steps. i.e `terraform plan -out $PLANFILE` For Atlantis commands to work, Atlantis needs to know the location where the plan file is. For that, you can use $PLANFILE which will contain the path of the plan file to be used in your custom steps. i.e `terraform plan -out $PLANFILE`
::: :::
### Examples ### Examples
```bash ```bash
# Runs apply for all unapplied plans from this pull request. # Runs apply for all unapplied plans from this pull request.
atlantis apply atlantis apply
@@ -122,6 +144,7 @@ atlantis apply -w staging
``` ```
### Options ### Options
* `-d directory` Apply the plan for this directory, relative to root of repo. Use `.` for root. * `-d directory` Apply the plan for this directory, relative to root of repo. Use `.` for root.
* `-p project` Apply the plan for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w`. * `-p project` Apply the plan for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w`.
* `-w workspace` Apply the plan for this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. * `-w workspace` Apply the plan for this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused.
@@ -131,6 +154,7 @@ atlantis apply -w staging
### Additional Terraform flags ### Additional Terraform flags
Because Atlantis under the hood is running `terraform apply plan.tfplan`, any Terraform options that would change the `plan` are ignored, ex: Because Atlantis under the hood is running `terraform apply plan.tfplan`, any Terraform options that would change the `plan` are ignored, ex:
* `-target=resource` * `-target=resource`
* `-var 'foo=bar'` * `-var 'foo=bar'`
* `-var-file=myfile.tfvars` * `-var-file=myfile.tfvars`
@@ -139,17 +163,22 @@ They're ignored because they can't be specified for an already generated planfil
If you would like to specify these flags, do it while running `atlantis plan`. If you would like to specify these flags, do it while running `atlantis plan`.
--- ---
## atlantis import ## atlantis import
```bash ```bash
atlantis import [options] ADDRESS ID -- [terraform import flags] atlantis import [options] ADDRESS ID -- [terraform import flags]
``` ```
### Explanation ### Explanation
Runs `terraform import` that matches the directory/project/workspace. Runs `terraform import` that matches the directory/project/workspace.
This command discards the terraform plan result. After an import and before an apply, another `atlantis plan` must be run again. This command discards the terraform plan result. After an import and before an apply, another `atlantis plan` must be run again.
To allow the `import` command requires [--allow-commands](server-configuration.md#allow-commands) configuration. To allow the `import` command requires [--allow-commands](server-configuration.md#allow-commands) configuration.
### Examples ### Examples
```bash ```bash
# Runs import # Runs import
atlantis import ADDRESS ID atlantis import ADDRESS ID
@@ -165,11 +194,13 @@ atlantis import -w staging ADDRESS ID
``` ```
::: tip ::: tip
* If import for_each resources, it requires a single quoted address. * If import for_each resources, it requires a single quoted address.
* ex. `atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0` * ex. `atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0`
::: :::
### Options ### Options
* `-d directory` Import a resource for this directory, relative to root of repo. Use `.` for root. * `-d directory` Import a resource for this directory, relative to root of repo. Use `.` for root.
* `-p project` Import a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`. * `-p project` Import a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`.
* `-w workspace` Import a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. * `-w workspace` Import a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused.
@@ -178,23 +209,30 @@ atlantis import -w staging ADDRESS ID
If `terraform import` requires additional arguments, like `-var 'foo=bar'` or `-var-file myfile.tfvars` If `terraform import` requires additional arguments, like `-var 'foo=bar'` or `-var-file myfile.tfvars`
append them to the end of the comment after `--`, e.g. append them to the end of the comment after `--`, e.g.
```
```shell
atlantis import -d dir 'aws_instance.example["foo"]' i-1234567890abcdef0 -- -var foo='bar' atlantis import -d dir 'aws_instance.example["foo"]' i-1234567890abcdef0 -- -var foo='bar'
``` ```
If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands).
--- ---
## atlantis state rm ## atlantis state rm
```bash ```bash
atlantis state [options] rm ADDRESS... -- [terraform state rm flags] atlantis state [options] rm ADDRESS... -- [terraform state rm flags]
``` ```
### Explanation ### Explanation
Runs `terraform state rm` that matches the directory/project/workspace. Runs `terraform state rm` that matches the directory/project/workspace.
This command discards the terraform plan result. After run state rm and before an apply, another `atlantis plan` must be run again. This command discards the terraform plan result. After run state rm and before an apply, another `atlantis plan` must be run again.
To allow the `state` command requires [--allow-commands](server-configuration.md#allow-commands) configuration. To allow the `state` command requires [--allow-commands](server-configuration.md#allow-commands) configuration.
### Examples ### Examples
```bash ```bash
# Runs state rm # Runs state rm
atlantis state rm ADDRESS1 ADDRESS2 atlantis state rm ADDRESS1 ADDRESS2
@@ -210,11 +248,13 @@ atlantis state -w staging rm ADDRESS
``` ```
::: tip ::: tip
* If run state rm to for_each resources, it requires a single quoted address. * If run state rm to for_each resources, it requires a single quoted address.
* ex. `atlantis state rm 'aws_instance.example["foo"]'` * ex. `atlantis state rm 'aws_instance.example["foo"]'`
::: :::
### Options ### Options
* `-d directory` Run state rm a resource for this directory, relative to root of repo. Use `.` for root. * `-d directory` Run state rm a resource for this directory, relative to root of repo. Use `.` for root.
* `-p project` Run state rm a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`. * `-p project` Run state rm a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`.
* `-w workspace` Run state rm a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. * `-w workspace` Run state rm a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused.
@@ -223,31 +263,40 @@ atlantis state -w staging rm ADDRESS
If `terraform state rm` requires additional arguments, like `-lock=false'` If `terraform state rm` requires additional arguments, like `-lock=false'`
append them to the end of the comment after `--`, e.g. append them to the end of the comment after `--`, e.g.
```
```shell
atlantis state -d dir rm 'aws_instance.example["foo"]' -- -lock=false atlantis state -d dir rm 'aws_instance.example["foo"]' -- -lock=false
``` ```
If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands).
--- ---
## atlantis unlock ## atlantis unlock
```bash ```bash
atlantis unlock atlantis unlock
``` ```
### Explanation ### Explanation
Removes all atlantis locks and discards all plans for this PR. Removes all atlantis locks and discards all plans for this PR.
To unlock a specific plan you can use the Atlantis UI. To unlock a specific plan you can use the Atlantis UI.
--- ---
## atlantis approve_policies ## atlantis approve_policies
```bash ```bash
atlantis approve_policies atlantis approve_policies
``` ```
### Explanation ### Explanation
Approves all current policy checking failures for the PR. Approves all current policy checking failures for the PR.
See also [policy checking](policy-checking.md). See also [policy checking](policy-checking.md).
### Options ### Options
* `--verbose` Append Atlantis log to comment. * `--verbose` Append Atlantis log to comment.

5
runatlantis.io/docs/using-slack-hooks.md
View File

@@ -48,8 +48,7 @@ webhooks:
If you are deploying Atlantis as a Helm chart, this can be implemented via the `config` parameter available for [chart customizations](https://github.com/runatlantis/helm-charts#customization): If you are deploying Atlantis as a Helm chart, this can be implemented via the `config` parameter available for [chart customizations](https://github.com/runatlantis/helm-charts#customization):
``` ```yaml
## Use Server Side Config, ## Use Server Side Config,
## ref: https://www.runatlantis.io/docs/server-configuration.html ## ref: https://www.runatlantis.io/docs/server-configuration.html
config: | config: |
@@ -62,6 +61,4 @@ config: |
channel: my-channel-id channel: my-channel-id
``` ```
The `apply` event information will be sent to the `my-channel-id` Slack channel. The `apply` event information will be sent to the `my-channel-id` Slack channel.

3
runatlantis.io/docs/webhook-secrets.md
View File

@@ -26,9 +26,11 @@ To mitigate, use repo allowlists and IP allowlists. See [Security](security.md#b
::: :::
## Generating A Webhook Secret ## Generating A Webhook Secret
You can use any random string generator to create your Webhook secret. It should be > 24 characters. You can use any random string generator to create your Webhook secret. It should be > 24 characters.
For example: For example:
* Generate via Ruby with `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'` * Generate via Ruby with `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`
* Generate online with [browserling: Generate Random Strings and Numbers](https://www.browserling.com/tools/random-string) * Generate online with [browserling: Generate Random Strings and Numbers](https://www.browserling.com/tools/random-string)
@@ -37,6 +39,7 @@ You must use **the same** webhook secret for each repo.
::: :::
## Next Steps ## Next Steps
* Record your secret * Record your secret
* You'll be using it later to [configure your webhooks](configuring-webhooks.md), however if you're * You'll be using it later to [configure your webhooks](configuring-webhooks.md), however if you're
following the [Installation Guide](installation-guide.md) then your next step is to following the [Installation Guide](installation-guide.md) then your next step is to

8
runatlantis.io/guide/test-drive.md
View File

@@ -1,18 +1,22 @@
# Test Drive # Test Drive
To test drive Atlantis on an example repo, download the latest release from To test drive Atlantis on an example repo, download the latest release from
[GitHub](https://github.com/runatlantis/atlantis/releases) [GitHub](https://github.com/runatlantis/atlantis/releases)
Once you've extracted the archive, run: Once you've extracted the archive, run:
```bash ```bash
./atlantis testdrive ./atlantis testdrive
``` ```
This mode sets up Atlantis on a test repo so you can try it out. It will This mode sets up Atlantis on a test repo so you can try it out. It will
- Fork an example Terraform project into your GitHub account - Fork an example Terraform project into your GitHub account
- Install Terraform (if not already in your PATH) - Install Terraform (if not already in your PATH)
- Install [ngrok](https://ngrok.com/) so we can expose Atlantis to GitHub - Install [ngrok](https://ngrok.com/) so we can expose Atlantis to GitHub
- Start Atlantis so you can execute commands on the pull request - Start Atlantis so you can execute commands on the pull request
## Next Steps ## Next Steps
* If you're ready to test out running Atlantis on **your repos** then read [Testing Locally](testing-locally.md).
* If you're ready to properly install Atlantis on real infrastructure then head over to the [Installation Guide](../docs/installation-guide.md). - If you're ready to test out running Atlantis on **your repos** then read [Testing Locally](testing-locally.md).
- If you're ready to properly install Atlantis on real infrastructure then head over to the [Installation Guide](../docs/installation-guide.md).

69
runatlantis.io/guide/testing-locally.md
View File

@@ -1,4 +1,5 @@
# Testing Locally # Testing Locally
These instructions are for running Atlantis **locally on your own computer** so you can test it out against These instructions are for running Atlantis **locally on your own computer** so you can test it out against
your own repositories before deciding whether to install it more permanently. your own repositories before deciding whether to install it more permanently.
@@ -8,19 +9,22 @@ If you want to set up a production-ready Atlantis installation, read [Deployment
Steps: Steps:
## Install Terraform ## Install Terraform
`terraform` needs to be in the `$PATH` for Atlantis. `terraform` needs to be in the `$PATH` for Atlantis.
Download from [Terraform](https://developer.hashicorp.com/terraform/downloads) Download from [Terraform](https://developer.hashicorp.com/terraform/downloads)
```
```shell
unzip path/to/terraform_*.zip -d /usr/local/bin unzip path/to/terraform_*.zip -d /usr/local/bin
``` ```
## Download Atlantis ## Download Atlantis
Get the latest release from [GitHub](https://github.com/runatlantis/atlantis/releases) Get the latest release from [GitHub](https://github.com/runatlantis/atlantis/releases)
and unpackage it. and unpackage it.
## Download Ngrok ## Download Ngrok
Atlantis needs to be accessible somewhere that github.com/gitlab.com/bitbucket.org or your GitHub/GitLab Enterprise installation can reach. Atlantis needs to be accessible somewhere that github.com/gitlab.com/bitbucket.org or your GitHub/GitLab Enterprise installation can reach.
One way to accomplish this is with ngrok, a tool that forwards your local port to a random One way to accomplish this is with ngrok, a tool that forwards your local port to a random
public hostname. public hostname.
@@ -28,17 +32,20 @@ public hostname.
[Download](https://ngrok.com/download) ngrok and `unzip` it. [Download](https://ngrok.com/download) ngrok and `unzip` it.
Start `ngrok` on port `4141` and take note of the hostname it gives you: Start `ngrok` on port `4141` and take note of the hostname it gives you:
```bash ```bash
./ngrok http 4141 ./ngrok http 4141
``` ```
In a new tab (where you'll soon start Atlantis) create an environment variable with In a new tab (where you'll soon start Atlantis) create an environment variable with
ngrok's hostname: ngrok's hostname:
```bash ```bash
URL="https://{YOUR_HOSTNAME}.ngrok.io" URL="https://{YOUR_HOSTNAME}.ngrok.io"
``` ```
## Create a Webhook Secret ## Create a Webhook Secret
GitHub and GitLab use webhook secrets so clients can verify that the webhooks came GitHub and GitLab use webhook secrets so clients can verify that the webhooks came
from them. from them.
::: warning ::: warning
@@ -48,14 +55,17 @@ to ensure the webhooks are coming from them.
::: :::
Create a random string of any length (you can use [random.org](https://www.random.org/strings/)) Create a random string of any length (you can use [random.org](https://www.random.org/strings/))
and set an environment variable: and set an environment variable:
```
```shell
SECRET="{YOUR_RANDOM_STRING}" SECRET="{YOUR_RANDOM_STRING}"
``` ```
## Add Webhook ## Add Webhook
Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo: Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo:
### GitHub or GitHub Enterprise Webhook ### GitHub or GitHub Enterprise Webhook
<details> <details>
<summary>Expand</summary> <summary>Expand</summary>
<ul> <ul>
@@ -81,6 +91,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details> </details>
### GitLab or GitLab Enterprise Webhook ### GitLab or GitLab Enterprise Webhook
<details> <details>
<summary>Expand</summary> <summary>Expand</summary>
<ul> <ul>
@@ -102,6 +113,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details> </details>
### Bitbucket Cloud (bitbucket.org) Webhook ### Bitbucket Cloud (bitbucket.org) Webhook
<details> <details>
<summary>Expand</summary> <summary>Expand</summary>
<ul> <ul>
@@ -123,6 +135,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details> </details>
### Bitbucket Server (aka Stash) Webhook ### Bitbucket Server (aka Stash) Webhook
<details> <details>
<summary>Expand</summary> <summary>Expand</summary>
<ul> <ul>
@@ -140,6 +153,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details> </details>
### Gitea Webhook ### Gitea Webhook
<details> <details>
<summary>Expand</summary> <summary>Expand</summary>
<ul> <ul>
@@ -169,38 +183,45 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</ul> </ul>
</details> </details>
## Create an access token for Atlantis ## Create an access token for Atlantis
We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing, We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing,
you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and
set commit statuses. set commit statuses.
### GitHub or GitHub Enterprise Access Token ### GitHub or GitHub Enterprise Access Token
- Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token) - Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
- create a token with **repo** scope - create a token with **repo** scope
- set the token as an environment variable - set the token as an environment variable
```
```shell
TOKEN="{YOUR_TOKEN}" TOKEN="{YOUR_TOKEN}"
``` ```
### GitLab or GitLab Enterprise Access Token ### GitLab or GitLab Enterprise Access Token
- follow [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token) - follow [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token)
- create a token with **api** scope - create a token with **api** scope
- set the token as an environment variable - set the token as an environment variable
```
```shell
TOKEN="{YOUR_TOKEN}" TOKEN="{YOUR_TOKEN}"
``` ```
### Bitbucket Cloud (bitbucket.org) Access Token ### Bitbucket Cloud (bitbucket.org) Access Token
- follow [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/) - follow [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
- Label the password "atlantis" - Label the password "atlantis"
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them - Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
- set the token as an environment variable - set the token as an environment variable
```
```shell
TOKEN="{YOUR_TOKEN}" TOKEN="{YOUR_TOKEN}"
``` ```
### Bitbucket Server (aka Stash) Access Token ### Bitbucket Server (aka Stash) Access Token
- Click on your avatar in the top right and select **Manage account** - Click on your avatar in the top right and select **Manage account**
- Click **HTTP access tokens** in the sidebar - Click **HTTP access tokens** in the sidebar
- Click **Create token** - Click **Create token**
@@ -208,11 +229,13 @@ TOKEN="{YOUR_TOKEN}"
- Give the token **Read** Project permissions and **Write** Pull request permissions - Give the token **Read** Project permissions and **Write** Pull request permissions
- Choose an Expiry option **Do not expire** or **Expire automatically** - Choose an Expiry option **Do not expire** or **Expire automatically**
- Click **Create** and set the token as an environment variable - Click **Create** and set the token as an environment variable
```
```shell
TOKEN="{YOUR_TOKEN}" TOKEN="{YOUR_TOKEN}"
``` ```
### Gite Access Token ### Gite Access Token
- Go to "Profile and Settings" > "Settings" in Gitea (top-right) - Go to "Profile and Settings" > "Settings" in Gitea (top-right)
- Go to "Applications" under "User Settings" in Gitea - Go to "Applications" under "User Settings" in Gitea
- Create a token under the "Manage Access Tokens" with the following permissions: - Create a token under the "Manage Access Tokens" with the following permissions:
@@ -221,6 +244,7 @@ TOKEN="{YOUR_TOKEN}"
- Record the access token - Record the access token
## Start Atlantis ## Start Atlantis
You're almost ready to start Atlantis, just set two more variables: You're almost ready to start Atlantis, just set two more variables:
```bash ```bash
@@ -231,9 +255,11 @@ REPO_ALLOWLIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO"
# server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo # server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo
# is under, **not the key** of the project. # is under, **not the key** of the project.
``` ```
Now you can start Atlantis. The exact command differs depending on your Git host: Now you can start Atlantis. The exact command differs depending on your Git host:
### GitHub Command ### GitHub Command
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -244,6 +270,7 @@ atlantis server \
``` ```
### GitHub Enterprise Command ### GitHub Enterprise Command
```bash ```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \ atlantis server \
@@ -256,6 +283,7 @@ atlantis server \
``` ```
### GitLab Command ### GitLab Command
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -266,6 +294,7 @@ atlantis server \
``` ```
### GitLab Enterprise Command ### GitLab Enterprise Command
```bash ```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \ atlantis server \
@@ -278,6 +307,7 @@ atlantis server \
``` ```
### Bitbucket Cloud (bitbucket.org) Command ### Bitbucket Cloud (bitbucket.org) Command
```bash ```bash
atlantis server \ atlantis server \
--atlantis-url="$URL" \ --atlantis-url="$URL" \
@@ -287,6 +317,7 @@ atlantis server \
``` ```
### Bitbucket Server (aka Stash) Command ### Bitbucket Server (aka Stash) Command
```bash ```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990 BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \ atlantis server \
@@ -330,16 +361,20 @@ atlantis server \
``` ```
## Create a pull request ## Create a pull request
Create a pull request so you can test Atlantis. Create a pull request so you can test Atlantis.
::: tip ::: tip
You could add a null resource as a test: You could add a null resource as a test:
```hcl ```hcl
resource "null_resource" "example" {} resource "null_resource" "example" {}
``` ```
Or just modify the whitespace in a file. Or just modify the whitespace in a file.
::: :::
### Autoplan ### Autoplan
You should see Atlantis logging about receiving the webhook and you should see the output of `terraform plan` on your repo. You should see Atlantis logging about receiving the webhook and you should see the output of `terraform plan` on your repo.
Atlantis tries to figure out the directory to plan in based on the files modified. Atlantis tries to figure out the directory to plan in based on the files modified.
@@ -347,28 +382,34 @@ If you need to customize the directories that Atlantis runs in or the commands i
or `.tfvars` files, see [atlantis.yaml Reference](../docs/repo-level-atlantis-yaml.md#reference). or `.tfvars` files, see [atlantis.yaml Reference](../docs/repo-level-atlantis-yaml.md#reference).
### Manual Plan ### Manual Plan
To manually `plan` in a specific directory or workspace, comment on the pull request using the `-d` or `-w` flags: To manually `plan` in a specific directory or workspace, comment on the pull request using the `-d` or `-w` flags:
```
```shell
atlantis plan -d mydir atlantis plan -d mydir
atlantis plan -w staging atlantis plan -w staging
``` ```
To add additional arguments to the underlying `terraform plan` you can use: To add additional arguments to the underlying `terraform plan` you can use:
```
```shell
atlantis plan -- -target=resource -var 'foo=bar' atlantis plan -- -target=resource -var 'foo=bar'
``` ```
### Apply ### Apply
If you'd like to `apply`, type a comment: `atlantis apply`. You can use the `-d` or `-w` flags to point If you'd like to `apply`, type a comment: `atlantis apply`. You can use the `-d` or `-w` flags to point
Atlantis at a specific plan. Otherwise it tries to apply the plan for the root directory. Atlantis at a specific plan. Otherwise it tries to apply the plan for the root directory.
## Real-time logs ## Real-time logs
The [real-time terraform output](../docs/streaming-logs.md) for your command can be found by clicking into the status check for a given project in a PR which The [real-time terraform output](../docs/streaming-logs.md) for your command can be found by clicking into the status check for a given project in a PR which
links to the log-streaming UI. This is a terminal UI where you can view your commands executing in real-time. links to the log-streaming UI. This is a terminal UI where you can view your commands executing in real-time.
## Next Steps ## Next Steps
* If things are working as expected you can `Ctrl-C` the `atlantis server` command and the `ngrok` command.
* Hopefully Atlantis is working with your repo and you're ready to move on to a [production-ready deployment](../docs/deployment.md). - If things are working as expected you can `Ctrl-C` the `atlantis server` command and the `ngrok` command.
* If it's not working as expected, you may need to customize how Atlantis runs with an `atlantis.yaml` file. - Hopefully Atlantis is working with your repo and you're ready to move on to a [production-ready deployment](../docs/deployment.md).
- If it's not working as expected, you may need to customize how Atlantis runs with an `atlantis.yaml` file.
See [atlantis.yaml use cases](../docs/repo-level-atlantis-yaml.md#use-cases). See [atlantis.yaml use cases](../docs/repo-level-atlantis-yaml.md#use-cases).
* Check out our [full documentation](../docs.md) for more details. - Check out our [full documentation](../docs.md) for more details.