public/atlantis
1
0
Fork 0
mirror of https://git.vectorsigma.ru/public/atlantis.git synced 2026-07-28 18:38:29 +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:
- 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
with:
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",
"sitemap-ts": "^1.6.1",
"vitepress": "^1.1.4",
"vue": "^3.4.27"
"vue": "^3.4.27",
"markdownlint-cli": "^0.40.0"
},
"scripts": {
"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",
"e2e": "playwright test"
}

5
runatlantis.io/contributing.md
View File

@@ -1,3 +1,6 @@
---
aside: false
---
# Atlantis Contributing Documentation
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).
:::
### Next Steps
## Next Steps
- [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)
- [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)
</details>
The following list shows the supported events:

5
runatlantis.io/docs.md
View File

@@ -1,3 +1,6 @@
---
aside: false
---
# Atlantis Documentation
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).
:::
### Next Steps
## Next Steps
* [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

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

@@ -1,9 +1,11 @@
# Git Host Access Credentials
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.
## Create an Atlantis user (optional)
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
@@ -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>
## Generating an Access Token
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:
* [GitHub](#github-user)
* [GitHub app](#github-app)
* [GitLab](#gitlab)
@@ -24,9 +28,10 @@ generate an access token. Read on for the instructions for your specific Git hos
* [Azure DevOps](#azure-devops)
### 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
- Record the 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 the token with **repo** scope
* Record the access token
::: 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:
![Atlantis status](./images/status.png)
@@ -35,16 +40,16 @@ Your Atlantis user must also have "Write permissions" (for repos in an organizat
### GitHub app
#### Create the GitHub App Using Atlantis
::: warning
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.
- 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.
- 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`.
* 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
* 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`
* 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).
@@ -58,11 +63,11 @@ GitHub App handles the webhook calls by itself, hence there is no need to create
#### Manually Creating the GitHub app
- Create the GitHub app as an Administrator
- 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)
- 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`.
* Create the GitHub app as an Administrator
* 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)
* 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`.
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.
:::
| Type | Access |
| --------------- | ------------------- |
| Administration | Read-only |
| Checks | Read and write |
| Commit statuses | Read and write |
| Contents | Read and write |
| Issues | Read and write |
| Metadata | Read-only (default) |
| Pull requests | Read and write |
| Webhooks | Read and write |
| Members | Read-only |
| Type | Access |
| --------------- | ------------------- |
| Administration | Read-only |
| Checks | Read and write |
| Commit statuses | Read and write |
| Contents | Read and write |
| Issues | Read and write |
| Metadata | Read-only (default) |
| Pull requests | Read and write |
| Webhooks | Read and write |
| Members | Read-only |
### 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
- Record the 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
* Record the access token
### Gitea
- Go to "Profile and Settings" > "Settings" in Gitea (top-right)
- Go to "Applications" under "User Settings" in Gitea
- Create a token under the "Manage Access Tokens" with the following permissions:
- issue: Read and Write
- repository: Read and Write
- user: Read
- Record the access token
* Go to "Profile and Settings" > "Settings" in Gitea (top-right)
* Go to "Applications" under "User Settings" in Gitea
* Create a token under the "Manage Access Tokens" with the following permissions:
* issue: Read and Write
* repository: Read and Write
* user: Read
* Record the access token
### 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"
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
- Record the access token
* 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"
* 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)
- Click on your avatar in the top right and select **Manage account**
- Click **Personal access tokens** in the sidebar
- Click **Create a token**
- Name the token **atlantis**
- Give the token **Read** Project permissions and **Write** Pull request permissions
- Click **Create** and record the access token
* Click on your avatar in the top right and select **Manage account**
* Click **Personal access tokens** in the sidebar
* Click **Create a token**
* Name the token **atlantis**
* 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.
### 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"
- The minimum scopes required for this token are:
- Code (Read & Write)
- Code (Status)
- Member Entitlement Management (Read)
- Record the access token
* 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"
* The minimum scopes required for this token are:
* Code (Read & Write)
* Code (Status)
* Member Entitlement Management (Read)
* Record the access token
## 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).

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
| Name | Type | Required | Description |
|------------|-----------------------------------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | [ [Path](api-endpoints.md#path) ] | Yes | Paths to the projects to run the plan |
| PR | int | No | Pull Request number |
| Name | Type | Required | Description |
|------------|---------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | Path | Yes | Paths to the projects to run the plan |
| PR | int | No | Pull Request number |
##### Path
#### Path
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.
| Name | Type | Required | Description |
@@ -96,18 +96,18 @@ Execute [atlantis apply](using-atlantis.md#atlantis-apply) on the specified repo
#### Parameters
| Name | Type | Required | Description |
|------------|-------------------------------------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | [ [Path](api-endpoints.md#path-1) ] | Yes | Paths to the projects to run the apply |
| PR | int | No | Pull Request number |
| Name | Type | Required | Description |
|------------|--------|----------|------------------------------------------|
| Repository | string | Yes | Name of the Terraform repository |
| Ref | string | Yes | Git reference, like a branch name |
| Type | string | Yes | Type of the VCS provider (Github/Gitlab) |
| Paths | Path | Yes | Paths to the projects to run the apply |
| PR | int | No | Pull Request number |
##### Path
#### Path
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.
| Name | Type | Required | Description |

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

@@ -1,44 +1,53 @@
# Automerging
Atlantis can be configured to automatically merge a pull request after all plans have
been successfully applied.
![Automerge](./images/automerge.png)
## How To Enable
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. Setting `automerge: true` in the repo's `atlantis.yaml` file:
```yaml
version: 3
automerge: true
projects:
- dir: .
```
:::tip NOTE
If a repo has an `atlantis.yaml` file, then each project in the repo needs
to be configured under the `projects` key.
:::
## How to Disable
If automerge is enabled, you can disable it for a single `atlantis apply`
command with the `--auto-merge-disabled` option.
## Requirements
### All Plans Must Succeed
When automerge is enabled, **all plans** in a pull request **must succeed** before
**any** plans can be applied.
For example, imagine this scenario:
1. I open a pull request that makes changes to two Terraform projects, in `dir1/`
and `dir2/`.
1. The plan for `dir2/` fails because my Terraform syntax is wrong.
In this scenario, I can't run
```
```shell
atlantis apply -d dir1
```
Even though that plan succeeded, because **all** plans must succeed for **any** plans
to be saved.
@@ -47,8 +56,9 @@ autoplan. Then I will be able to apply both plans.
### 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.
## Permissions
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
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.
The algorithm it uses is as follows:
1. Get list of all modified files in pull request
1. Filter to those containing `.tf`
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).
## Example
Given the directory structure:
```
```plain
.
├── modules
│   └── module1
@@ -26,21 +30,25 @@ Given the directory structure:
* 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
* 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.
* Or you could manually plan with `atlantis plan -d <dir>`
* 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.
* 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`
into `project1/`, see that there was a `main.tf` file and so run plan in `project1/`
## 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.
This scenario can happen if:
* Atlantis restarts
* You are running multiple Atlantis instances behind a load balancer
## Customizing
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.
See
* [Disabling Autoplanning](repo-level-atlantis-yaml.md#disabling-autoplanning)
* [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.
## Branch
If set to `branch` (the default), Atlantis will check out the source branch
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`.
## Merge
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
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:
- 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.
- 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.
* 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.
* 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 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
## Intro
Atlantis requires certain conditions be satisfied **before** `atlantis apply` and `atlantis import`
commands can be run:
@@ -9,31 +10,41 @@ commands can be run:
* [UnDiverged](#undiverged) - requires pull requests to be ahead of the base branch
## 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`:
![Mergeable Apply Requirement](./images/apply-requirement.png)
## Supported Requirements
### Approved
The `approved` requirement will prevent applies unless the pull request is approved
by at least one person other than the author.
#### Usage
The `approved` requirement by:
1. Creating a `repos.yaml` file with the `apply_requirements` key:
```yaml
repos:
- id: /.*/
apply_requirements: [approved]
```
1. Or by allowing an `atlantis.yaml` file to specify the `apply_requirements` key in the `repos.yaml` config:
#### repos.yaml
**repos.yaml**
```yaml
repos:
- id: /.*/
allowed_overrides: [apply_requirements]
```
#### atlantis.yaml
**atlantis.yaml**
```yaml
version: 3
projects:
@@ -42,7 +53,9 @@ The `approved` requirement by:
```
#### Meaning
Each VCS provider has different rules around who can approve:
* **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/)
* **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
The `mergeable` requirement will prevent applies unless a pull request is able to be merged.
#### Usage
Set the `mergeable` requirement by:
1. Creating a `repos.yaml` file with the `apply_requirements` key:
```yaml
repos:
- 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:
#### repos.yaml
**repos.yaml**
```yaml
repos:
- id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
```
#### atlantis.yaml
**atlantis.yaml**
```yaml
version: 3
projects:
@@ -86,6 +106,7 @@ Set the `mergeable` requirement by:
```
#### Meaning
Each VCS provider has a different concept of "mergeability":
::: warning
@@ -95,10 +116,12 @@ See also the `branch` keyword in [Server Side Repo Config](server-side-repo-conf
:::
#### 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
all pull requests are mergeable unless there is a conflict.
If you set up Protected Branches then you can enforce:
* Requiring certain status checks to be passing
* Requiring certain people 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
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.
@@ -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.
#### Bitbucket.org (Bitbucket Cloud) and Bitbucket Server (Stash)
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.
@@ -132,9 +157,11 @@ If you need a specific check, please
[open an issue](https://github.com/runatlantis/atlantis/issues/new).
#### 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:
* Require a minimum number of reviewers
* Allow users to approve their own changes
* 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
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.
#### Usage
You can set the `undiverged` requirement by:
1. Creating a `repos.yaml` file with `plan_requirements`, `apply_requirements` and `import_requirements` keys:
```yaml
repos:
- id: /.*/
@@ -159,15 +190,19 @@ You can set the `undiverged` requirement by:
apply_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:
#### repos.yaml
**repos.yaml**
```yaml
repos:
- id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
```
#### atlantis.yaml
**atlantis.yaml**
```yaml
version: 3
projects:
@@ -176,7 +211,9 @@ You can set the `undiverged` requirement by:
apply_requirements: [undiverged]
import_requirements: [undiverged]
```
#### Meaning
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
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.
## Setting Command Requirements
As mentioned above, you can set command requirements via flags, in `repos.yaml`, or in `atlantis.yaml` if `repos.yaml`
allows the override.
### Flags Override
Flags **override** any `repos.yaml` or `atlantis.yaml` settings so they are equivalent to always
having that apply requirement set.
### Project-Specific Settings
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.
```yaml
repos:
- id: /.*/
@@ -220,7 +262,9 @@ If you only want some projects/repos to have apply requirements, then you must
config.
For example if I have two directories, `staging` and `production`, I might use:
#### repos.yaml
**repos.yaml:**
```yaml
repos:
- 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
```
#### atlantis.yaml
**atlantis.yaml:**
```yaml
version: 3
projects:
@@ -247,13 +292,16 @@ If you only want some projects/repos to have apply requirements, then you must
```
### Multiple Requirements
You can set any or all of `approved`, `mergeable`, and `undiverged` requirements.
## Who Can Apply?
Once the apply requirement is satisfied, **anyone** that can comment on the pull
request can run the actual `atlantis apply` command.
## 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 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)

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

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

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

@@ -1,7 +1,9 @@
# Configuring Webhooks
Atlantis needs to receive Webhooks from your Git host so that it can respond to pull request events.
:::tip Prerequisites
* You have created an [access credential](access-credentials.md)
* You have created a [webhook secret](webhook-secrets.md)
* 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.
## 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.
::: 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 installing on a single repository, navigate to the repository home page and click **Settings**.
- Select **Webhooks** or **Hooks** in the sidebar
- Click **Add webhook**
- 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`**
- double-check you added `/events` to the end of your URL.
- set **Content type** to `application/json`
- set **Secret** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- select **Let me select individual events**
- check the boxes
- **Pull request reviews**
- **Pushes**
- **Issue comments**
- **Pull requests**
- leave **Active** checked
- click **Add webhook**
- See [Next Steps](#next-steps)
* Select **Webhooks** or **Hooks** in the sidebar
* Click **Add webhook**
* 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`**
* double-check you added `/events` to the end of your URL.
* set **Content type** to `application/json`
* set **Secret** to the Webhook Secret you generated previously
* **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
* select **Let me select individual events**
* check the boxes
* **Pull request reviews**
* **Pushes**
* **Issue comments**
* **Pull requests**
* leave **Active** checked
* click **Add webhook**
* See [Next Steps](#next-steps)
## 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`**
- double-check you added `/events` to the end of your URL.
- set **Secret Token** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- check the boxes
- **Push events**
- **Comments**
- **Merge Request events**
- leave **Enable SSL verification** checked
- click **Add webhook**
- See [Next Steps](#next-steps)
* 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`**
* double-check you added `/events` to the end of your URL.
* set **Secret Token** to the Webhook Secret you generated previously
* **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
* check the boxes
* **Push events**
* **Comments**
* **Merge Request events**
* leave **Enable SSL verification** checked
* click **Add webhook**
* See [Next Steps](#next-steps)
## 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)
- 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`**
- double-check you added `/events` to the end of your URL.
- set **Secret** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Select **Custom Events...**
- Check the boxes
- **Repository events > Push**
- **Issue events > Issue Comment**
- **Pull Request events > Pull Request**
- **Pull Request events > Pull Request Comment**
- **Pull Request events > Pull Request Reviewed**
- **Pull Request events > Pull Request Synchronized**
- Leave **Active** checked
- Click **Add Webhook**
- See [Next Steps](#next-steps)
* Click **Settings > Webhooks** in the top- and then sidebar
* Click **Add webhook > Gitea** (Gitea webhooks are service specific, but this works)
* 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`**
* double-check you added `/events` to the end of your URL.
* set **Secret** to the Webhook Secret you generated previously
* **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
* Select **Custom Events...**
* Check the boxes
* **Repository events > Push**
* **Issue events > Issue Comment**
* **Pull Request events > Pull Request**
* **Pull Request events > Pull Request Comment**
* **Pull Request events > Pull Request Reviewed**
* **Pull Request events > Pull Request Synchronized**
* Leave **Active** checked
* Click **Add Webhook**
* See [Next Steps](#next-steps)
## Bitbucket Cloud (bitbucket.org)
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Add webhook**
- Enter "Atlantis" for **Title**
- 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`**
- double-check you added `/events` to the end of your URL.
- Keep **Status** as Active
- Don't check **Skip certificate validation** because NGROK has a valid cert.
- Select **Choose from a full list of triggers**
- Under **Repository** **un**check everything
- Under **Issues** leave everything **un**checked
- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created
- Click **Save**
* Go to your repo's home page
* Click **Settings** in the sidebar
* Click **Webhooks** under the **WORKFLOW** section
* Click **Add webhook**
* Enter "Atlantis" for **Title**
* 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`**
* double-check you added `/events` to the end of your URL.
* Keep **Status** as Active
* Don't check **Skip certificate validation** because NGROK has a valid cert.
* Select **Choose from a full list of triggers**
* Under **Repository** **un**check everything
* Under **Issues** leave everything **un**checked
* 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">
- See [Next Steps](#next-steps)
* See [Next Steps](#next-steps)
## Bitbucket Server (aka Stash)
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Create webhook**
- Enter "Atlantis" for **Name**
- 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`**
- Double-check you added `/events` to the end of your URL.
- Set **Secret** to the Webhook Secret you generated previously
- **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
- Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added
- Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 600px;">
- See [Next Steps](#next-steps)
* Go to your repo's home page
* Click **Settings** in the sidebar
* Click **Webhooks** under the **WORKFLOW** section
* Click **Create webhook**
* Enter "Atlantis" for **Name**
* 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`**
* Double-check you added `/events` to the end of your URL.
* Set **Secret** to the Webhook Secret you generated previously
* **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret.
* Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added
* Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 600px;">
* See [Next Steps](#next-steps)
## 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.
- Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName`
- Select **Project settings** in the lower-left corner
- 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.
- 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.
- Click **Create subscription** or the green plus icon to add a new webhook
- Scroll to the bottom of the list and select **Web Hooks**
- Click **Next**
- 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
- 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`**
- 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**
- 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.
- Click **Finish**
* Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName`
* Select **Project settings** in the lower-left corner
* 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.
* 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.
* Click **Create subscription** or the green plus icon to add a new webhook
* Scroll to the bottom of the list and select **Web Hooks**
* Click **Next**
* 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
* 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`**
* 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**
* 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.
* 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:
- Pull request created (you just added this one)
- Pull request updated
- Pull request commented on
* Pull request created (you just added this one)
* Pull request updated
* Pull request commented on
- See [Next Steps](#next-steps)
* See [Next Steps](#next-steps)
## Next Steps
* 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'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
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
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
@@ -30,8 +32,8 @@ policies:
source: local
```
## 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:
```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
runs.
## Usage
Custom workflows can be specified in the Server-Side Repo Config or in the Repo-Level
`atlantis.yaml` files.
**Notes**
**Notes:**
* 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.
* 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.
## Use Cases
### .tfvars files
Given the structure:
```
```plain
.
└── project1
├── 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`
you could define two workflows:
```yaml
# repos.yaml or atlantis.yaml
workflows:
@@ -39,7 +43,7 @@ workflows:
extra_args: ["-var-file", "staging.tfvars"]
# NOTE: no need to define the apply stage because it will default
# to the normal apply stage.
production:
plan:
steps:
@@ -61,7 +65,9 @@ workflows:
- state_rm:
extra_args: ["-lock=false"]
```
Then in your repo-level `atlantis.yaml` file, you would reference the workflows:
```yaml
# atlantis.yaml
version: 3
@@ -79,20 +85,27 @@ workflows:
# If you didn't define the workflows in your server-side repos.yaml config,
# you would define them here instead.
```
When you want to apply the plans, you can comment
```
```shell
atlantis apply -p project1-staging
```
and
```
```shell
atlantis apply -p project1-production
```
Where `-p` refers to the project name.
### Adding extra arguments to Terraform commands
If you need to append flags to `terraform plan` or `apply` temporarily, you can
append flags on a comment following `--`, for example commenting:
```
```shell
atlantis plan -- -lock=false
```
@@ -129,6 +142,7 @@ workflows:
```
### Custom init/plan/apply Commands
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.
@@ -146,11 +160,11 @@ workflows:
- run:
command: terraform init -input=false
output: hide
# If you're using workspaces you need to select the workspace using the
# $WORKSPACE environment variable.
- run: terraform workspace select $WORKSPACE
# You MUST output the plan using -out $PLANFILE because Atlantis expects
# plans to be in a specific location.
- run: terraform plan -input=false -refresh -out $PLANFILE
@@ -161,14 +175,15 @@ workflows:
```
### CDKTF
Here are the requirements to enable [CDKTF](https://developer.hashicorp.com/terraform/cdktf)
- A custom image with `CDKTF` installed
- 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
* A custom image with `CDKTF` installed
* 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
by CDKTF will be add to the Atlantis modified file list.
- 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.
* 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.
#### Custom Image
@@ -191,6 +206,7 @@ ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true
OR
`atlantis server --config config.yaml`
```yaml
# config.yaml
autoplan-file-list: "**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json"
@@ -202,6 +218,7 @@ include-git-untracked-files: true
Use `pre_workflow_hooks`
`atlantis server --repo-config="repos.yaml"`
```yaml
# repos.yaml
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
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. 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`,
@@ -242,6 +259,7 @@ generating the `cdk.tf.json` Terraform files.
1. Atlantis then runs `terraform` workflows in the respective directories as usual.
### Terragrunt
Atlantis supports running custom commands in place of the default Atlantis
commands. We can use this functionality to enable
[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.
Given a directory structure:
```
```plain
.
└── live
   ├── prod
@@ -314,6 +333,7 @@ workflows:
```
If using the repo's `atlantis.yaml` file you would use the following config:
```yaml
version: 3
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.
::: warning
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).
@@ -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.
### Running custom commands
Atlantis supports running completely custom commands. In this example, we want to run
a script after every `apply`:
@@ -374,17 +394,19 @@ workflows:
```
::: tip Notes
* 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.
* 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
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
the redirect, the script would block the Atlantis workflow.
:::
### Custom Backend Config
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.
We're then using `.tfvars` files to load different variables for each environment.
@@ -409,12 +431,14 @@ workflows:
- plan:
extra_args: [-var-file=production.tfvars]
```
::: warning NOTE
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.
:::
You would then reference the workflows in your repo-level `atlantis.yaml`:
```yaml
version: 3
projects:
@@ -427,7 +451,9 @@ projects:
```
## Reference
### Workflow
```yaml
plan:
apply:
@@ -443,6 +469,7 @@ state_rm:
| state_rm | [Stage](#stage) | `steps: [init, state_rm]` | no | How to run state rm for this project. |
### Stage
```yaml
steps:
- 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. |
### Step
#### Built-In Commands
Steps can be a single string for a built-in command.
```yaml
- init
- plan
@@ -465,12 +495,15 @@ Steps can be a single string for a built-in command.
- import
- state_rm
```
| 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 |
#### Built-In Command With Extra Args
A map from string to `extra_args` for a built-in command with extra arguments.
```yaml
- init:
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:
extra_args: [arg1, arg2]
```
| 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
A custom command can be written in 2 ways
Compact:
```yaml
- run: custom-command arg1 arg2
```
| Key | Type | Default | Required | Description |
|-----|--------|---------|----------|----------------------|
| run | string | none | no | Run a custom command |
Full
```yaml
- run:
- run:
command: custom-command arg1 arg2
output: show
```
| 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.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
* `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
* `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.
* `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`.
* `DIR` - Absolute path to the current directory.
* `PLANFILE` - Absolute path to the location where Atlantis expects the plan to
* `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`.
* `DIR` - Absolute path to the current directory.
* `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
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
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.
* `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`.
* `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_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.
* `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.
* `PULL_NUM` - Pull request number or ID, ex. `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`.
* `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`.
* `COMMENT_ARGS` - Any additional flags passed in the comment on the pull request. Flags are separated by commas and
* `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`.
* `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_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.
* `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.
* `PULL_NUM` - Pull request number or ID, ex. `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`.
* `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`.
* `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`.
* 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
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
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
The `env` command allows you to set environment variables that will be available
to all steps defined **below** the `env` step.
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
as the environment variable value.
```yaml
- env:
name: ENV_NAME
@@ -564,24 +606,29 @@ as the environment variable value.
name: ENV_NAME_2
command: 'echo "dynamic-value-$(date)"'
```
| 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.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` |
::: tip Notes
* `env` `command`'s can use any of the built-in environment variables available
to `run` commands.
to `run` commands.
:::
#### Multiple Environment Variables `multienv` Command
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.
```yaml
- multienv: custom-command
```
| Key | Type | Default | Required | Description |
|----------|--------|---------|----------|--------------------------------------------------------------------------------|
| 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.
::: tip Notes
* `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
This page covers getting Atlantis up and running in your infrastructure.
::: tip Prerequisites
* You have created [access credentials](access-credentials.md) for your Atlantis user
* You have created a [webhook secret](webhook-secrets.md)
:::
## Architecture Overview
### Runtime
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
Atlantis [Docker image](https://ghcr.io/runatlantis/atlantis).
### 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.
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
@@ -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.
### Data
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
to re-run `plan`. Because of this, you may want to provision a persistent disk
@@ -31,6 +36,7 @@ for Atlantis.
## Deployment
Pick your deployment type:
* [Kubernetes Helm Chart](#kubernetes-helm-chart)
* [Kubernetes Manifests](#kubernetes-manifests)
* [Kubernetes Kustomize](#kubernetes-kustomize)
@@ -40,21 +46,27 @@ Pick your deployment type:
* [Docker](#docker)
* [Roll Your Own](#roll-your-own)
### Kubernetes Helm Chart
Atlantis has an [official Helm chart](https://github.com/runatlantis/helm-charts/tree/main/charts/atlantis)
To install:
1. Add the runatlantis helm chart repository to helm
```bash
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. Create a `values.yaml` file by running
```bash
helm inspect values runatlantis/atlantis > values.yaml
```
1. Edit `values.yaml` and add your access credentials and webhook secret
```yaml
# for example
github:
@@ -62,28 +74,33 @@ To install:
token: bar
secret: baz
```
1. Edit `values.yaml` and set your `orgAllowlist` (see [Repo Allowlist](server-configuration.md#repo-allowlist) for more information)
```yaml
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)
for documentation)
1. Run
```sh
helm install atlantis runatlantis/atlantis -f values.yaml
```
If you are using helm v2, run:
```sh
helm install -f values.yaml runatlantis/atlantis
```
Atlantis should be up and running in minutes! See [Next Steps](#next-steps) for
what to do next.
### Kubernetes Manifests
If you'd like to use a raw Kubernetes manifest, we offer either a
[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
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.
Regardless of whether you choose a Deployment or StatefulSet, first create a Secret with the webhook secret and access token:
```bash
echo -n "yourtoken" > token
echo -n "yoursecret" > webhook-secret
kubectl create secret generic atlantis-vcs --from-file=token --from-file=webhook-secret
```
::: tip Note
If you're using Bitbucket Cloud then there is no webhook secret since it's not supported.
:::
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).
* 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!
@@ -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.
#### StatefulSet Manifest
<details>
<summary>Show...</summary>
@@ -289,10 +310,11 @@ spec:
selector:
app.kubernetes.io/name: atlantis
```
</details>
#### Deployment Manifest
<details>
<summary>Show...</summary>
@@ -437,9 +459,11 @@ spec:
selector:
app.kubernetes.io/name: atlantis
```
</details>
#### Routing and SSL
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
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.
Example:
```yaml
bases:
- github.com/runatlantis/atlantis//kustomize
@@ -482,7 +507,6 @@ patchesStrategicMerge:
#### Required
```yaml
...
containers:
@@ -571,16 +595,19 @@ containers:
```
### OpenShift
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
OpenShift runs Docker images with random user id's that use `/` as their home directory.
### AWS 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)
and then check out the [Next Steps](#next-steps).
### Google Kubernetes Engine (GKE)
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,
@@ -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).
### 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.
After it is deployed, see [Next Steps](#next-steps).
### Docker
Atlantis has an [official](https://ghcr.io/runatlantis/atlantis) Docker image: `ghcr.io/runatlantis/atlantis`.
#### 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:
1. Create a custom docker file
```dockerfile
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.
1. Build your Docker image
```bash
docker build -t {YOUR_DOCKER_ORG}/atlantis-custom .
```
1. Run your image
```bash
docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN
```
### 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).
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.
### Roll Your Own
If you want to roll your own Atlantis installation, you can get the `atlantis`
binary from [GitHub](https://github.com/runatlantis/atlantis/releases)
or use the [official Docker image](https://ghcr.io/runatlantis/atlantis).
#### Startup Command
The exact flags to `atlantis server` depends on your Git host:
##### GitHub
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -651,6 +687,7 @@ atlantis server \
```
##### GitHub Enterprise
```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
@@ -663,6 +700,7 @@ atlantis server \
```
##### GitLab
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -673,6 +711,7 @@ atlantis server \
```
##### GitLab Enterprise
```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
@@ -685,6 +724,7 @@ atlantis server \
```
##### Gitea
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -696,6 +736,7 @@ atlantis server \
```
##### Bitbucket Cloud (bitbucket.org)
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -705,6 +746,7 @@ atlantis server \
```
##### Bitbucket Server (aka Stash)
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
@@ -733,20 +775,21 @@ atlantis server \
```
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
- `$TOKEN` is the access token you created. If you don't want this to be passed
* `$URL` is the URL that Atlantis can be reached at
* `$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
(see [Configuration](server-configuration.md#environment-variables))
or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN` or `ATLANTIS_GITEA_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
you can specify it in a config file
(see [Configuration](server-configuration.md#environment-variables))
or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET` or
`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/*`.
See [--repo-allowlist](server-configuration.md#repo-allowlist) for more details.
@@ -757,5 +800,6 @@ restart it in case of failure.
:::
## Next Steps
* 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).

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

@@ -1,4 +1,5 @@
# FAQ
**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`.

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

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

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

@@ -1,6 +1,8 @@
# Installation Guide
This guide is for installing a **production-ready** instance of Atlantis onto your
infrastructure:
1. First, ensure your Terraform setup meets the Atlantis **requirements**
* See [Requirements](requirements.md)
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
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
@@ -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.
:::
## Why
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
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.
## Viewing Locks
To view locks, go to the URL that Atlantis is hosted at:
![Locks View](./images/locks-ui.png)
@@ -40,6 +42,7 @@ You can click on a lock to view its details:
</p>
## Unlocking
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,
@@ -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.
## 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 is doing is running `terraform plan` and `apply` and so all of the
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 approvals may be cleared either by re-planing, or by issuing the following command:
```
```shell
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:
```
```yaml
policies:
owners:
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.
```
```yaml
repos:
- id: github.com/myorg/example-repo
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.
```
```rego
package main
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.
### 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:
@@ -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.
For server side config:
```yml
# repos.yaml
repos:
@@ -216,6 +216,7 @@ repos:
```
For repo level `atlantis.yaml` config:
```yml
version: 3
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
back to the PR as a comment.
## Usage
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
workflow using [Infracost](https://www.infracost.io/docs/integrations/cicd/#cicd-integrations), then create a summary report after all workflows have completed.
```yaml
# repos.yaml
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 |
::: tip Notes
* `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_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
they do not surface their output back to the PR as a comment.
## Usage
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
Atlantis runs Terraform by simply executing `terraform plan` and `apply` commands
on the server Atlantis is hosted on.
Just like when you run Terraform locally, Atlantis needs credentials for your
specific provider.
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
credentials. Read their docs.
* If you're running Atlantis in a cloud then many clouds have ways to give cloud API access
to applications running on them, ex:
* [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)
* [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)
* 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.
* 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.
:::
## AWS Specific Info
### Multiple AWS Accounts
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").
@@ -41,6 +43,7 @@ won't work for multiple accounts since Atlantis wouldn't know which environment
Terraform with.
### 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.
Setting the `session_name` allows you to trace API calls made through Atlantis back to a specific
user and repo via CloudWatch:
@@ -89,5 +92,6 @@ You can still set these variables yourself using the `extra_args` configuration.
:::
## Next Steps
* 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)

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

@@ -1,15 +1,17 @@
# Repo Level atlantis.yaml Config
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.
## Do I need an atlantis.yaml file?
`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.
Read through the [use-cases](#use-cases) to determine if you need it.
## Enabling atlantis.yaml
By default, all repos are allowed to have an `atlantis.yaml` file,
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
more details.
**Notes**
**Notes:**
* 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)
@@ -146,7 +149,9 @@ grep -P 'backend[\s]+"s3"' **/*.tf |
```
## Use Cases
### Disabling Autoplanning
```yaml
version: 3
projects:
@@ -154,6 +159,7 @@ projects:
autoplan:
enabled: false
```
This will stop Atlantis automatically running plan when `project1/` is updated
in a pull request.
@@ -177,7 +183,7 @@ Parallel plans and applies work across both multiple directories and multiple wo
Given the directory structure:
```
```plain
.
├── modules
│   └── 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:
```yaml
version: 3
projects:
@@ -202,12 +207,14 @@ projects:
```
Note:
* `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file)
* The paths are relative to the project's directory.
* `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.
### Supporting Terraform Workspaces
```yaml
version: 3
projects:
@@ -216,34 +223,44 @@ projects:
- dir: project1
workspace: production
```
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.
If you want to `plan` or `apply` for a specific workspace you can use
```
```shell
atlantis plan -w staging -d project1
```
and
```
```shell
atlantis apply -w staging -d project1
```
### Using .tfvars files
See [Custom Workflow Use Cases: Using .tfvars files](custom-workflows.md#tfvars-files)
### 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
See [Custom Workflow Use Cases: Custom init/plan/apply Commands](custom-workflows.md#custom-init-plan-apply-commands)
### Terragrunt
See [Custom Workflow Use Cases: Terragrunt](custom-workflows.md#terragrunt)
### Running custom commands
See [Custom Workflow Use Cases: Running custom commands](custom-workflows.md#running-custom-commands)
### Terraform Versions
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:
@@ -257,7 +274,9 @@ projects:
Atlantis will automatically download and use this version.
### Requiring Approvals For Production
In this example, we only want to require `apply` approvals for the `production` directory.
```yaml
version: 3
projects:
@@ -267,12 +286,14 @@ projects:
apply_requirements: [approved]
import_requirements: [approved]
```
:::warning
`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).
:::
### Order of planning/applying
```yaml
version: 3
abort_on_execution_order_fail: true
@@ -282,12 +303,13 @@ projects:
- dir: project2
execution_order_group: 1
```
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.
`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.
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.
The following configuration is an example of how to use execution order groups and depends_on together to enforce dependencies between projects.
```yaml
version: 3
projects:
@@ -322,6 +345,7 @@ projects:
workspace: production
workflow: infra
```
the `depends_on` feature will make sure that `production` is not applied before `staging` for example.
::: 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:
`Can't apply your project unless you apply its dependencies`
:::
### Autodiscovery Config
```yaml
autodiscover:
mode: "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.
@@ -342,6 +369,7 @@ projects will be discovered only if the repo has no `projects` configured.
autodiscover:
mode: "disabled"
```
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.
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:
mode: "enabled"
```
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.
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.
### Custom Backend Config
See [Custom Workflow Use Cases: Custom Backend Config](custom-workflows.md#custom-backend-config)
## Reference
### Top-Level Keys
```yaml
version: 3
automerge: false
@@ -371,6 +403,7 @@ projects:
workflows:
allowed_regexp_prefixes:
```
| Key | Type | Default | Required | Description |
|-------------------------------|--------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 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. |
| 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
```yaml
name: myname
branch: /mybranch/
@@ -410,9 +444,9 @@ workflow: myworkflow
| 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). |
| 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. |
| 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. |
| 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. |
| 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. |
::: tip
@@ -422,11 +456,13 @@ Atlantis supports this but requires the `name` key to be specified. See [Custom
:::
### Autoplan
```yaml
enabled: true
when_modified: ["*.tf", "terragrunt.hcl", ".terraform.lock.hcl"]
```
| Key | Type | Default | Required | Description |
|-----------------------|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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
Atlantis works with most Git hosts and Terraform setups. Read on to confirm
it works with yours.
## Git Host
Atlantis integrates with the following Git hosts:
* GitHub (public, private or enterprise)
@@ -14,6 +15,7 @@ Atlantis integrates with the following Git hosts:
* Azure DevOps
## Terraform 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
statefile back to version control.
@@ -24,17 +26,20 @@ storage from Terraform Cloud. This is fully supported by Atlantis.
:::
## Repository Structure
Atlantis supports any Terraform repository structure, for example:
### Single Terraform Project At Repo Root
```
```plain
.
├── main.tf
└── ...
```
### Multiple Project Folders
```
```plain
.
├── project1
│   ├── main.tf
@@ -45,7 +50,8 @@ Atlantis supports any Terraform repository structure, for example:
```
### Modules
```
```plain
.
├── project1
│   ├── main.tf
@@ -55,10 +61,12 @@ Atlantis supports any Terraform repository structure, for example:
   ├── main.tf
└── ...
```
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.
### Terraform Workspaces
### Terraform 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
@@ -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)
### .tfvars Files
```
```plain
.
├── production.tfvars
│── staging.tfvars
└── main.tf
```
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}`.
See [atlantis.yaml Use Cases](custom-workflows.md#tfvars-files) for more details.
### Multiple Repos
Atlantis supports multiple repos as well–as long as there is a webhook configured
for each repo.
## Terraform Versions
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).
## Next Steps
* If your Terraform setup meets the Atlantis requirements, continue the installation
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
## 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.
Atlantis could be exploited by
* 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)
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)
```tf
resource "null_resource" "null" {
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`.
* 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)
::: danger
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).
## Mitigations
### 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.
### 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)
because anyone can open up a pull request from their fork to your repo.
### `--repo-allowlist`
Atlantis requires you to specify a allowlist of repositories it will accept webhooks from via the `--repo-allowlist` flag.
For example:
* Specific repositories: `--repo-allowlist=github.com/runatlantis/atlantis,github.com/runatlantis/atlantis-tests`
* Your whole organization: `--repo-allowlist=github.com/runatlantis/*`
* 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.
### Protect Terraform Planning
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
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.
To prevent this, you could:
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. 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.
### `--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)
from pull requests by adding
`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.
### Webhook Secrets
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.
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 supports sending a basic authentication header in all webhook events. This requires using an HTTPS URL for your webhook location.
### SSL/HTTPS
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`
flags.
### 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.
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
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
and what users can do in repo-level `atlantis.yaml` files.
## Do I Need A Server-Side Config File?
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 |
| 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. |
| 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. |
| 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` |

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.
```yaml
metrics:
prometheus:
endpoint: "/metrics"
```
To see all the metrics exposed from atlantis service, make a GET request to the `/metrics` endpoint.
```bash
curl localhost:4141/metrics
# 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
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
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:
* [Free Remote State Management](https://app.terraform.io)
* Terraform Cloud Paid Tiers
* 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.
## Using Atlantis With Free Remote State Storage
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. 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)
@@ -23,6 +26,7 @@ That's it! Atlantis will run as normal and your state will be stored in Terrafor
Cloud.
## Using Atlantis With Terraform Cloud Remote Operations or 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).
@@ -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.
### Why?
Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to features like:
* Real-time streaming output
* Ability to cancel in-progress commands
* 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.
### Getting Started
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. 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. [Pass the token to Atlantis](#passing-the-token-to-atlantis)
## Generating a Terraform Cloud/Enterprise Token
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.
### Team Token
To generate a team token, click on **Settings** in the top bar, then **Teams** in
the sidebar.
Choose an existing team or create a new one.
Enable the **Manage Workspaces** permission, then scroll down to **Team API Token**.
### User Token
To generate a user token, click on your avatar, then **User Settings**, then
**Tokens** in the sidebar.
Ensure the **Manage Workspaces** permission is enabled for this user's team.
## Passing The Token To Atlantis
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
@@ -87,12 +99,14 @@ Under the hood, Atlantis is generating a `~/.terraformrc` file.
If you already had a `~/.terraformrc` file where Atlantis is running,
then you'll need to manually
add the credentials block to that file:
```
```hcl
...
credentials "app.terraform.io" {
token = "xxxx"
}
```
instead of using the `ATLANTIS_TFE_TOKEN` environment variable, since Atlantis
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`).
## Via `atlantis.yaml`
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:
```yaml
version: 3
projects:
- dir: .
terraform_version: v1.1.5
```
See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#terraform-versions) for more details.
## 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):
#### Exactly version 1.2.9
### Exactly version 1.2.9
```tf
terraform {
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
terraform {
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
terraform {
required_version = "~> 1.2"
}
```
#### Any version that is at least 1.2.0
### Any version that is at least 1.2.0
```tf
terraform {
required_version = ">= 1.2.0"
}
```
See [Terraform `required_version`](https://developer.hashicorp.com/terraform/language/settings#specifying-a-required-terraform-version) for reference.
::: 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`),
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).
`ListenAndServeTLS` acts identically to [ListenAndServe](https://pkg.go.dev/net/http#ListenAndServe),
except that it expects HTTPS connections.
Additionally, files containing a certificate and matching private key for the server must be provided.
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.
except that it expects HTTPS connections.
Additionally, files containing a certificate and matching private key for the server must be provided.
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.
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
```
@@ -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 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 From v2 To v3
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),
@@ -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.
The only change from v2 to v3 is that we're parsing custom `run` steps differently.
```yaml
# atlantis.yaml
workflows:
@@ -18,33 +20,38 @@ workflows:
steps:
- run: my custom command
```
<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
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:
```yaml
# version: 2
- run: "printf \'print me\'"
```
You can now write this in version 3 as:
```yaml
# version: 3
- run: "printf 'print me'"
```
## Upgrading From V1 To V3
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.
### Single atlantis.yaml
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.
For example, if you had a directory structure:
```
```plain
.
├── project1
│ └── atlantis.yaml
@@ -53,7 +60,8 @@ For example, if you had a directory structure:
```
Then your new structure would look like:
```
```plain
.
├── atlantis.yaml
├── project1
@@ -61,6 +69,7 @@ Then your new structure would look like:
```
And your `atlantis.yaml` would look something like:
```yaml
version: 2
projects:
@@ -80,13 +89,16 @@ workflows:
We will talk more about `workflows` below.
### Terraform Version
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:
```yaml
terraform_version: 0.11.0
```
Then your new config would be:
```yaml
version: 2
projects:
@@ -95,9 +107,11 @@ projects:
```
### Workflows
Workflows are the new way to set all `pre_*`, `post_*` and `extra_arguments`.
Each `project` can have a custom workflow via the `workflow` key.
```yaml
version: 2
projects:
@@ -106,6 +120,7 @@ projects:
```
Workflows are defined as a top-level key:
```yaml
version: 2
projects:
@@ -118,6 +133,7 @@ workflows:
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:
```yaml
...
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 only customizing the commands that happen during `plan` then your config
will look like:
```yaml
...
workflows:
@@ -143,7 +160,9 @@ workflows:
```
#### Extra Arguments
`extra_arguments` is now specified as follows. Given a previous config:
```yaml
extra_arguments:
- command_name: init
@@ -158,6 +177,7 @@ extra_arguments:
```
Your config would now look like:
```yaml
...
workflows:
@@ -174,8 +194,8 @@ workflows:
extra_args: ["-lock=false"]
```
#### Pre/Post Commands
Instead of using `pre_*` or `post_*`, you now can insert your custom commands
before/after the built-in commands. Given a previous config:
@@ -202,6 +222,7 @@ post_apply:
```
Your config would now look like:
```yaml
...
workflows:

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

@@ -5,6 +5,7 @@ Atlantis triggers commands via pull request comments.
::: tip
You can use following executable names.
* `atlantis help`
* `atlantis` is executable name. You can configure by [Executable Name](server-configuration.md#executable-name).
* `run help`
@@ -16,32 +17,44 @@ You can use following executable names.
Currently, Atlantis supports the following commands.
---
## atlantis help
```bash
atlantis help
```
### Explanation
View help
---
## atlantis version
```bash
atlantis version
```
### Explanation
Print the output of 'terraform version'.
---
## atlantis plan
```bash
atlantis plan [options] -- [terraform plan flags]
```
### Explanation
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.
### Examples
```bash
# Runs plan for any projects that Atlantis thinks were modified.
# If an `atlantis.yaml` file is specified, runs plan on the projects that
@@ -59,8 +72,9 @@ atlantis plan -w staging
```
### Options
* `-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.
* `-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.
@@ -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`
you can append them to the end of the comment after `--`, ex.
```
```shell
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).
### Using the -destroy Flag
#### Example
To perform a destructive plan that will destroy resources you can use the `-destroy` flag like this:
```bash
atlantis plan -- -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.
:::
---
## atlantis apply
```bash
atlantis apply [options] -- [terraform apply flags]
```
### Explanation
Runs `terraform apply` for the plan that matches the directory/project/workspace.
::: 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`
:::
### Examples
```bash
# Runs apply for all unapplied plans from this pull request.
atlantis apply
@@ -122,6 +144,7 @@ atlantis apply -w staging
```
### Options
* `-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`.
* `-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
Because Atlantis under the hood is running `terraform apply plan.tfplan`, any Terraform options that would change the `plan` are ignored, ex:
* `-target=resource`
* `-var 'foo=bar'`
* `-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`.
---
## atlantis import
```bash
atlantis import [options] ADDRESS ID -- [terraform import flags]
```
### Explanation
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.
To allow the `import` command requires [--allow-commands](server-configuration.md#allow-commands) configuration.
### Examples
```bash
# Runs import
atlantis import ADDRESS ID
@@ -165,11 +194,13 @@ atlantis import -w staging ADDRESS ID
```
::: tip
* If import for_each resources, it requires a single quoted address.
* ex. `atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0`
:::
### Options
* `-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`.
* `-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`
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'
```
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
```bash
atlantis state [options] rm ADDRESS... -- [terraform state rm flags]
```
### Explanation
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.
To allow the `state` command requires [--allow-commands](server-configuration.md#allow-commands) configuration.
### Examples
```bash
# Runs state rm
atlantis state rm ADDRESS1 ADDRESS2
@@ -210,11 +248,13 @@ atlantis state -w staging rm ADDRESS
```
::: tip
* If run state rm to for_each resources, it requires a single quoted address.
* ex. `atlantis state rm 'aws_instance.example["foo"]'`
:::
### Options
* `-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`.
* `-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'`
append them to the end of the comment after `--`, e.g.
```
```shell
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).
---
## atlantis unlock
```bash
atlantis unlock
```
### Explanation
Removes all atlantis locks and discards all plans for this PR.
To unlock a specific plan you can use the Atlantis UI.
---
## atlantis approve_policies
```bash
atlantis approve_policies
```
### Explanation
Approves all current policy checking failures for the PR.
See also [policy checking](policy-checking.md).
### Options
* `--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):
```
```yaml
## Use Server Side Config,
## ref: https://www.runatlantis.io/docs/server-configuration.html
config: |
@@ -62,6 +61,4 @@ config: |
channel: my-channel-id
```
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
You can use any random string generator to create your Webhook secret. It should be > 24 characters.
For example:
* 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)
@@ -37,6 +39,7 @@ You must use **the same** webhook secret for each repo.
:::
## Next Steps
* Record your secret
* 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

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

@@ -1,18 +1,22 @@
# Test Drive
To test drive Atlantis on an example repo, download the latest release from
[GitHub](https://github.com/runatlantis/atlantis/releases)
Once you've extracted the archive, run:
```bash
./atlantis testdrive
```
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
- Install Terraform (if not already in your PATH)
- Install [ngrok](https://ngrok.com/) so we can expose Atlantis to GitHub
- Start Atlantis so you can execute commands on the pull request
## 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
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.
@@ -8,19 +9,22 @@ If you want to set up a production-ready Atlantis installation, read [Deployment
Steps:
## Install Terraform
`terraform` needs to be in the `$PATH` for Atlantis.
Download from [Terraform](https://developer.hashicorp.com/terraform/downloads)
```
```shell
unzip path/to/terraform_*.zip -d /usr/local/bin
```
## Download Atlantis
Get the latest release from [GitHub](https://github.com/runatlantis/atlantis/releases)
and unpackage it.
## Download Ngrok
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
public hostname.
@@ -28,17 +32,20 @@ public hostname.
[Download](https://ngrok.com/download) ngrok and `unzip` it.
Start `ngrok` on port `4141` and take note of the hostname it gives you:
```bash
./ngrok http 4141
```
In a new tab (where you'll soon start Atlantis) create an environment variable with
ngrok's hostname:
```bash
URL="https://{YOUR_HOSTNAME}.ngrok.io"
```
## Create a Webhook Secret
GitHub and GitLab use webhook secrets so clients can verify that the webhooks came
from them.
::: 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/))
and set an environment variable:
```
```shell
SECRET="{YOUR_RANDOM_STRING}"
```
## Add Webhook
Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo:
### GitHub or GitHub Enterprise Webhook
<details>
<summary>Expand</summary>
<ul>
@@ -81,6 +91,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details>
### GitLab or GitLab Enterprise Webhook
<details>
<summary>Expand</summary>
<ul>
@@ -102,6 +113,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details>
### Bitbucket Cloud (bitbucket.org) Webhook
<details>
<summary>Expand</summary>
<ul>
@@ -123,6 +135,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details>
### Bitbucket Server (aka Stash) Webhook
<details>
<summary>Expand</summary>
<ul>
@@ -140,6 +153,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</details>
### Gitea Webhook
<details>
<summary>Expand</summary>
<ul>
@@ -169,38 +183,45 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
</ul>
</details>
## 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,
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.
### 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 token with **repo** scope
- set the token as an environment variable
```
```shell
TOKEN="{YOUR_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)
- create a token with **api** scope
- set the token as an environment variable
```
```shell
TOKEN="{YOUR_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/)
- Label the password "atlantis"
- 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
```
```shell
TOKEN="{YOUR_TOKEN}"
```
### Bitbucket Server (aka Stash) Access Token
- Click on your avatar in the top right and select **Manage account**
- Click **HTTP access tokens** in the sidebar
- Click **Create token**
@@ -208,11 +229,13 @@ TOKEN="{YOUR_TOKEN}"
- Give the token **Read** Project permissions and **Write** Pull request permissions
- Choose an Expiry option **Do not expire** or **Expire automatically**
- Click **Create** and set the token as an environment variable
```
```shell
TOKEN="{YOUR_TOKEN}"
```
### Gite Access Token
- Go to "Profile and Settings" > "Settings" in Gitea (top-right)
- Go to "Applications" under "User Settings" in Gitea
- Create a token under the "Manage Access Tokens" with the following permissions:
@@ -221,6 +244,7 @@ TOKEN="{YOUR_TOKEN}"
- Record the access token
## Start Atlantis
You're almost ready to start Atlantis, just set two more variables:
```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
# is under, **not the key** of the project.
```
Now you can start Atlantis. The exact command differs depending on your Git host:
### GitHub Command
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -244,6 +270,7 @@ atlantis server \
```
### GitHub Enterprise Command
```bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
@@ -256,6 +283,7 @@ atlantis server \
```
### GitLab Command
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -266,6 +294,7 @@ atlantis server \
```
### GitLab Enterprise Command
```bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
@@ -278,6 +307,7 @@ atlantis server \
```
### Bitbucket Cloud (bitbucket.org) Command
```bash
atlantis server \
--atlantis-url="$URL" \
@@ -287,6 +317,7 @@ atlantis server \
```
### Bitbucket Server (aka Stash) Command
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
@@ -330,16 +361,20 @@ atlantis server \
```
## Create a pull request
Create a pull request so you can test Atlantis.
::: tip
You could add a null resource as a test:
```hcl
resource "null_resource" "example" {}
```
Or just modify the whitespace in a file.
:::
### Autoplan
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.
@@ -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).
### Manual Plan
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 -w staging
```
To add additional arguments to the underlying `terraform plan` you can use:
```
```shell
atlantis plan -- -target=resource -var 'foo=bar'
```
### Apply
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.
## 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
links to the log-streaming UI. This is a terminal UI where you can view your commands executing in real-time.
## 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 it's not working as expected, you may need to customize how Atlantis runs with an `atlantis.yaml` file.
- 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 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).
* Check out our [full documentation](../docs.md) for more details.
- Check out our [full documentation](../docs.md) for more details.