-- 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**
-- 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**
+* 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/* `show` - preserve the full output
* `hide` - hide output from comment (still visible in the real-time streaming output)
* `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
*`show` - preserve the full output
* `hide` - hide output from comment (still visible in the real-time streaming output)
* `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. ::: diff --git a/runatlantis.io/docs/deployment.md b/runatlantis.io/docs/deployment.md index 72e8ca9763..dfe5ae27cc 100644 --- a/runatlantis.io/docs/deployment.md +++ b/runatlantis.io/docs/deployment.md @@ -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 `
Show...
@@ -289,10 +310,11 @@ spec: selector: app.kubernetes.io/name: atlantis ``` -Show...
@@ -437,9 +459,11 @@ spec: selector: app.kubernetes.io/name: atlantis ``` +*(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
*(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
*(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
*(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
*(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
*(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
*(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
*(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. | diff --git a/runatlantis.io/docs/requirements.md b/runatlantis.io/docs/requirements.md index 01eb710f06..a661ac3508 100644 --- a/runatlantis.io/docs/requirements.md +++ b/runatlantis.io/docs/requirements.md @@ -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) diff --git a/runatlantis.io/docs/security.md b/runatlantis.io/docs/security.md index ac0ea6e215..0f5d8df4c6 100644 --- a/runatlantis.io/docs/security.md +++ b/runatlantis.io/docs/security.md @@ -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. diff --git a/runatlantis.io/docs/server-configuration.md b/runatlantis.io/docs/server-configuration.md index 8e79254c08..439e55d481 100644 --- a/runatlantis.io/docs/server-configuration.md +++ b/runatlantis.io/docs/server-configuration.md @@ -1,11 +1,12 @@ # Server Configuration + This page explains how to configure the `atlantis server` command. Configuration to `atlantis server` can be specified via command line flags, environment variables, a config file or a mix of the three. - ## Environment Variables + All flags can be specified as environment variables. 1. Take the flag name, ex. `--gh-user` @@ -23,11 +24,13 @@ The flag `--atlantis-url` is set by the environment variable `ATLANTIS_ATLANTIS_ ::: ## Config File + All flags can also be specified via a YAML config file. To use a YAML config file, run `atlantis server --config /path/to/config.yaml`. The keys of your config file should be the same as the flag names, ex. + ```yaml gh-token: ... log-level: ... @@ -39,40 +42,49 @@ The `--config` config file is only used as an alternate way of setting `atlantis ::: ## Precedence + Values are chosen in this order: + 1. Flags 1. Environment Variables 1. Config File - ## Flags + ### `--allow-commands` + ```bash atlantis server --allow-commands=version,plan,apply,unlock,approve_policies # or ATLANTIS_ALLOW_COMMANDS='version,plan,apply,unlock,approve_policies' ``` + List of allowed commands to be run on the Atlantis server, Defaults to `version,plan,apply,unlock,approve_policies` Notes: - * Accepts a comma separated list, ex. `command1,command2`. - * `version`, `plan`, `apply`, `unlock`, `approve_policies`, `import`, `state` and `all` are available. - * `all` is a special keyword that allows all commands. If pass `all` then all other commands will be ignored. + +* Accepts a comma separated list, ex. `command1,command2`. +* `version`, `plan`, `apply`, `unlock`, `approve_policies`, `import`, `state` and `all` are available. +* `all` is a special keyword that allows all commands. If pass `all` then all other commands will be ignored. ### `--allow-draft-prs` + ```bash atlantis server --allow-draft-prs # or ATLANTIS_ALLOW_DRAFT_PRS=true ``` + Respond to pull requests from draft prs. Defaults to `false`. ### `--allow-fork-prs` + ```bash atlantis server --allow-fork-prs # or ATLANTIS_ALLOW_FORK_PRS=true ``` + Respond to pull requests from forks. Defaults to `false`. :::warning SECURITY WARNING @@ -84,33 +96,40 @@ Values are chosen in this order: ::: ### `--api-secret` + ```bash atlantis server --api-secret="secret" # or (recommended) ATLANTIS_API_SECRET="secret" ``` + Required secret used to validate requests made to the [`/api/*` endpoints](api-endpoints.md). ### `--atlantis-url` + ```bash atlantis server --atlantis-url="https://my-domain.com:9090/basepath" # or ATLANTIS_ATLANTIS_URL=https://my-domain.com:9090/basepath ``` + Specify the URL that Atlantis is accessible from. Used in the Atlantis UI and in links from pull request comments. Defaults to `http://$(hostname):$port` where `$port` is from the [`--port`](#port) flag. Supports a basepath if you're hosting Atlantis under a path. Notes: - * If a load balancer with a non http/https port (not the one defined in the `--port` flag) is used, update the URL to include the port like in the example above. - * This URL is used as the `details` link next to each atlantis job to view the job's logs. + +* If a load balancer with a non http/https port (not the one defined in the `--port` flag) is used, update the URL to include the port like in the example above. +* This URL is used as the `details` link next to each atlantis job to view the job's logs. ### `--autodiscover-mode` + ```bash atlantis server --autodiscover-mode="
` html tag.
### `--disable-repo-locking`
+
```bash
atlantis server --disable-repo-locking
# or
ATLANTIS_DISABLE_REPO_LOCKING=true
```
+
Stops atlantis from locking projects and or workspaces when running terraform.
### `--disable-unlock-label`
+
```bash
atlantis server --disable-unlock-label do-not-unlock
# or
ATLANTIS_DISABLE_UNLOCK_LABEL="do-not-unlock"
```
+
Stops atlantis from unlocking a pull request with this label. Defaults to "" (feature disabled).
### `--emoji-reaction`
+
```bash
atlantis server --emoji-reaction thumbsup
# or
ATLANTIS_EMOJI_REACTION=thumbsup
```
+
The emoji reaction to use for marking processed comments. Currently supported on Azure DevOps, GitHub and GitLab.
Defaults to `eyes`.
### `--enable-diff-markdown-format`
+
```bash
atlantis server --enable-diff-markdown-format
# or
ATLANTIS_ENABLE_DIFF_MARKDOWN_FORMAT=true
```
+
Enable Atlantis to format Terraform plan output into a markdown-diff friendly format for color-coding purposes.
Useful to enable for use with GitHub.
### `--enable-policy-checks`
+
```bash
atlantis server --enable-policy-checks
# or
ATLANTIS_ENABLE_POLICY_CHECKS=true
```
+
Enables atlantis to run server side policies on the result of a terraform plan. Policies are defined in [server side repo config](server-side-repo-config.md#reference).
### `--enable-regexp-cmd`
+
```bash
atlantis server --enable-regexp-cmd
# or
ATLANTIS_ENABLE_REGEXP_CMD=true
```
+
Enable Atlantis to use regular expressions to run plan/apply commands against defined project names when `-p` flag is passed with it.
This can be used to run all defined projects (with the `name` key) in `atlantis.yaml` using `atlantis plan -p .*`.
@@ -453,16 +525,19 @@ and set `--autoplan-modules` to `false`.
:::
### `--executable-name`
+
```bash
atlantis server --executable-name="atlantis"
# or
ATLANTIS_EXECUTABLE_NAME="atlantis"
```
+
Comment command trigger executable name. Defaults to `atlantis`.
This is useful when running multiple Atlantis servers against a single repository.
### `--fail-on-pre-workflow-hook-error`
+
```bash
atlantis server --fail-on-pre-workflow-hook-error
# or
@@ -472,35 +547,43 @@ and set `--autoplan-modules` to `false`.
Fail and do not run the requested Atlantis command if any of the pre workflow hooks error.
### `--gitea-base-url`
+
```bash
atlantis server --gitea-base-url="http://your-gitea.corp:7990/basepath"
# or
ATLANTIS_GITEA_BASE_URL="http://your-gitea.corp:7990/basepath"
```
+
Base URL of Gitea installation. Must include `http://` or `https://`. Defaults to `https://gitea.com` if left empty/absent.
### `--gitea-token`
+
```bash
atlantis server --gitea-token="token"
# or (recommended)
ATLANTIS_GITEA_TOKEN="token"
```
+
Gitea app password of API user.
### `--gitea-user`
+
```bash
atlantis server --gitea-user="myuser"
# or
ATLANTIS_GITEA_USER="myuser"
```
+
Gitea username of API user.
### `--gitea-webhook-secret`
+
```bash
atlantis server --gitea-webhook-secret="secret"
# or (recommended)
ATLANTIS_GITEA_WEBHOOK_SECRET="secret"
```
+
Secret used to validate Gitea webhooks.
::: warning SECURITY WARNING
@@ -509,44 +592,50 @@ and set `--autoplan-modules` to `false`.
:::
### `--gitea-page-size`
+
```bash
atlantis server --gitea-page-size=30
# or (recommended)
ATLANTIS_GITEA_PAGE_SIZE=30
```
+
Number of items on a single page in Gitea paged responses.
::: warning Configuration dependent
The default value conforms to the Gitea server's standard config setting: DEFAULT_PAGING_NUM
- The highest valid value depends on the Gitea server's config setting: MAX_RESPONSE_ITEMS
+ The highest valid value depends on the Gitea server's config setting: MAX_RESPONSE_ITEMS
:::
### `--gh-allow-mergeable-bypass-apply`
+
```bash
atlantis server --gh-allow-mergeable-bypass-apply
# or
ATLANTIS_GH_ALLOW_MERGEABLE_BYPASS_APPLY=true
```
+
Feature flag to enable ability to use `mergeable` mode with required apply status check.
### `--gh-app-id`
+
```bash
atlantis server --gh-app-id="00000"
# or
ATLANTIS_GH_APP_ID="00000"
```
+
GitHub app ID. If set, GitHub authentication will be performed as [an installation](https://docs.github.com/en/rest/apps/installations).
::: tip
A GitHub app can be created by starting Atlantis first, then pointing your browser at
- ```
+ ```shell
$(hostname)/github-app/setup
```
You'll be redirected to GitHub to create a new app, and will then be redirected to
- ```
+ ```shell
$(hostname)/github-app/exchange-code?code=some-code
```
@@ -554,11 +643,13 @@ and set `--autoplan-modules` to `false`.
:::
### `--gh-app-key`
+
```bash
atlantis server --gh-app-key="-----BEGIN RSA PRIVATE KEY-----(...)"
# or
ATLANTIS_GH_APP_KEY="-----BEGIN RSA PRIVATE KEY-----(...)"
```
+
The PEM encoded private key for the GitHub App.
::: warning SECURITY WARNING
@@ -566,44 +657,54 @@ and set `--autoplan-modules` to `false`.
:::
### `--gh-app-key-file`
+
```bash
atlantis server --gh-app-key-file="path/to/app-key.pem"
# or
ATLANTIS_GH_APP_KEY_FILE="path/to/app-key.pem"
```
+
Path to a GitHub App PEM encoded private key file. If set, GitHub authentication will be performed as [an installation](https://docs.github.com/en/rest/apps/installations).
### `--gh-app-slug`
+
```bash
atlantis server --gh-app-slug="myappslug"
# or
ATLANTIS_GH_APP_SLUG="myappslug"
```
+
A slugged version of GitHub app name shown in pull requests comments, etc (not `Atlantis App` but something like `atlantis-app`). Atlantis uses the value of this parameter to identify the comments it has left on GitHub pull requests. This is used for functions such as `--hide-prev-plan-comments`. You need to obtain this value from your GitHub app, one way is to go to your App settings and open "Public page" from the left sidebar. Your `--gh-app-slug` value will be the last part of the URL, e.g `https://github.com/apps/`.
### `--gh-hostname`
+
```bash
atlantis server --gh-hostname="my.github.enterprise.com"
# or
ATLANTIS_GH_HOSTNAME="my.github.enterprise.com"
```
+
Hostname of your GitHub Enterprise installation. If using [GitHub.com](https://github.com),
don't set. Defaults to `github.com`.
### `--gh-org`
+
```bash
atlantis server --gh-org="myorgname"
# or
ATLANTIS_GH_ORG="myorgname"
```
+
GitHub organization name. Set to enable creating a private GitHub app for this organization.
### `--gh-team-allowlist`
+
```bash
atlantis server --gh-team-allowlist="myteam:plan, secteam:apply, DevOps Team:apply, DevOps Team:import"
# or
ATLANTIS_GH_TEAM_ALLOWLIST="myteam:plan, secteam:apply, DevOps Team:apply, DevOps Team:import"
```
+
In versions v0.21.0 and later, the GitHub team name can be a name or a slug.
In versions v0.20.1 and below, the Github team name required the case sensitive team name.
@@ -618,27 +719,33 @@ and set `--autoplan-modules` to `false`.
:::
### `--gh-token`
+
```bash
atlantis server --gh-token="token"
# or (recommended)
ATLANTIS_GH_TOKEN="token"
```
+
GitHub token of API user.
### `--gh-user`
+
```bash
atlantis server --gh-user="myuser"
# or
ATLANTIS_GH_USER="myuser"
```
+
GitHub username of API user.
### `--gh-webhook-secret`
+
```bash
atlantis server --gh-webhook-secret="secret"
# or (recommended)
ATLANTIS_GH_WEBHOOK_SECRET="secret"
```
+
Secret used to validate GitHub webhooks (see [GitHub: Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)).
::: warning SECURITY WARNING
@@ -647,36 +754,44 @@ and set `--autoplan-modules` to `false`.
:::
### `--gitlab-hostname`
+
```bash
atlantis server --gitlab-hostname="my.gitlab.enterprise.com"
# or
ATLANTIS_GITLAB_HOSTNAME="my.gitlab.enterprise.com"
```
+
Hostname of your GitLab Enterprise installation. If using [Gitlab.com](https://gitlab.com),
don't set. Defaults to `gitlab.com`.
### `--gitlab-token`
+
```bash
atlantis server --gitlab-token="token"
# or (recommended)
ATLANTIS_GITLAB_TOKEN="token"
```
+
GitLab token of API user.
### `--gitlab-user`
+
```bash
atlantis server --gitlab-user="myuser"
# or
ATLANTIS_GITLAB_USER="myuser"
```
+
GitLab username of API user.
### `--gitlab-webhook-secret`
+
```bash
atlantis server --gitlab-webhook-secret="secret"
# or (recommended)
ATLANTIS_GITLAB_WEBHOOK_SECRET="secret"
```
+
Secret used to validate GitLab webhooks.
::: warning SECURITY WARNING
@@ -685,71 +800,86 @@ and set `--autoplan-modules` to `false`.
:::
### `--help`
+
```bash
atlantis server --help
```
+
View help.
### `--hide-prev-plan-comments`
+
```bash
atlantis server --hide-prev-plan-comments
# or
ATLANTIS_HIDE_PREV_PLAN_COMMENTS=true
```
+
Hide previous plan comments to declutter PRs. This is only supported in
GitHub and GitLab currently. This is not enabled by default. When using Github App, you need to set `--gh-app-slug` to enable this feature.
### `--hide-unchanged-plan-comments`
+
```bash
atlantis server --hide-unchanged-plan-comments
# or
ATLANTIS_HIDE_UNCHANGED_PLAN_COMMENTS=true
```
+
Remove no-changes plan comments from the pull request.
This is useful when you have many projects and want to keep the pull request clean from useless comments.
### `--include-git-untracked-files`
+
```bash
atlantis server --include-git-untracked-files
# or
ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true
```
+
Include git untracked files in the Atlantis modified file list.
Used for example with CDKTF pre-workflow hooks that dynamically generate
Terraform files.
### `--locking-db-type`
+
```bash
atlantis server --locking-db-type=""
# or
ATLANTIS_LOCKING_DB_TYPE=""
```
+
The locking database type to use for storing plan and apply locks. Defaults to `boltdb`.
Notes:
- * If set to `boltdb`, only one process may have access to the boltdb instance.
- * If set to `redis`, then `--redis-host`, `--redis-port`, and `--redis-password` must be set.
+
+* If set to `boltdb`, only one process may have access to the boltdb instance.
+* If set to `redis`, then `--redis-host`, `--redis-port`, and `--redis-password` must be set.
### `--log-level`
+
```bash
atlantis server --log-level=""
# or
ATLANTIS_LOG_LEVEL=""
```
+
Log level. Defaults to `info`.
### `--markdown-template-overrides-dir`
+
```bash
atlantis server --markdown-template-overrides-dir="path/to/templates/"
# or
ATLANTIS_MARKDOWN_TEMPLATE_OVERRIDES_DIR="path/to/templates/"
```
+
This will be available in v0.21.0.
Directory where Atlantis will read in overrides for markdown templates used to render comments on pull requests.
Markdown template overrides may be specified either in individual files, or all together in a single file. All template
- override files _must_ have the `.tmpl` extension, otherwise they will not be parsed.
+ override files *must* have the `.tmpl` extension, otherwise they will not be parsed.
Markdown templates which may have overrides can be found [here](https://github.com/runatlantis/atlantis/tree/main/server/events/templates)
@@ -759,67 +889,83 @@ This is useful when you have many projects and want to keep the pull request cle
Defaults to the atlantis home directory `/home/atlantis/.markdown_templates/` in `/$HOME/.markdown_templates`.
### `--parallel-apply`
+
```bash
atlantis server --parallel-apply
# or
ATLANTIS_PARALLEL_APPLY=true
```
+
Whether to run apply operations in parallel. Defaults to `false`. Explicit declaration in [repo config](repo-level-atlantis-yaml.md#run-plans-and-applies-in-parallel) takes precedence.
### `--parallel-plan`
+
```bash
atlantis server --parallel-plan
# or
ATLANTIS_PARALLEL_PLAN=true
```
+
Whether to run plan operations in parallel. Defaults to `false`. Explicit declaration in [repo config](repo-level-atlantis-yaml.md#run-plans-and-applies-in-parallel) takes precedence.
### `--parallel-pool-size`
+
```bash
atlantis server --parallel-pool-size=100
# or
ATLANTIS_PARALLEL_POOL_SIZE=100
```
+
Max size of the wait group that runs parallel plans and applies (if enabled). Defaults to `15`
### `--port`
+
```bash
atlantis server --port=4141
# or
ATLANTIS_PORT=4141
```
+
Port to bind to. Defaults to `4141`.
### `--quiet-policy-checks`
+
```bash
atlantis server --quiet-policy-checks
# or
ATLANTIS_QUIET_POLICY_CHECKS=true
```
+
Exclude policy check comments from pull requests unless there's an actual error from conftest. This also excludes warnings. Defaults to `false`.
### `--redis-db`
+
```bash
atlantis server --redis-db=0
# or
ATLANTIS_REDIS_DB=0
```
+
The Redis Database to use when using a Locking DB type of `redis`. Defaults to `0`.
### `--redis-host`
+
```bash
atlantis server --redis-host="localhost"
# or
ATLANTIS_REDIS_HOST="localhost"
```
+
The Redis Hostname for when using a Locking DB type of `redis`.
### `--redis-insecure-skip-verify`
+
```bash
atlantis server --redis-insecure-skip-verify=false
# or
ATLANTIS_REDIS_INSECURE_SKIP_VERIFY=false
```
+
Controls whether the Redis client verifies the Redis server's certificate chain and host name. If true, accepts any certificate presented by the server and any host name in that certificate. Defaults to `false`.
::: warning SECURITY WARNING
@@ -827,82 +973,97 @@ This is useful when you have many projects and want to keep the pull request cle
:::
### `--redis-password`
+
```bash
atlantis server --redis-password="password123"
# or (recommended)
ATLANTIS_REDIS_PASSWORD="password123"
```
+
The Redis Password for when using a Locking DB type of `redis`.
### `--redis-port`
+
```bash
atlantis server --redis-port=6379
# or
ATLANTIS_REDIS_PORT=6379
```
+
The Redis Port for when using a Locking DB type of `redis`. Defaults to `6379`.
### `--redis-tls-enabled`
+
```bash
atlantis server --redis-tls-enabled=false
# or
ATLANTIS_REDIS_TLS_ENABLED=false
```
+
Enables a TLS connection, with min version of 1.2, to Redis when using a Locking DB type of `redis`. Defaults to `false`.
### `--repo-allowlist`
+
```bash
# NOTE: Use single quotes to avoid shell expansion of *.
atlantis server --repo-allowlist='github.com/myorg/*'
# or
ATLANTIS_REPO_ALLOWLIST='github.com/myorg/*'
```
+
Atlantis requires you to specify an allowlist of repositories it will accept webhooks from.
Notes:
- * Accepts a comma separated list, ex. `definition1,definition2`
- * Format is `{hostname}/{owner}/{repo}`, ex. `github.com/runatlantis/atlantis`
- * `*` matches any characters, ex. `github.com/runatlantis/*` will match all repos in the runatlantis organization
- * An entry beginning with `!` negates it, ex. `github.com/foo/*,!github.com/foo/bar` will match all github repos in the `foo` owner *except* `bar`.
- * For Bitbucket Server: `{hostname}` is the domain without scheme and port, `{owner}` is the name of the project (not the key), and `{repo}` is the repo name
- * User (not project) repositories take on the format: `{hostname}/{full name}/{repo}` (e.g., `bitbucket.example.com/Jane Doe/myatlantis` for username `jdoe` and full name `Jane Doe`, which is not very intuitive)
- * For Azure DevOps the allowlist takes one of two forms: `{owner}.visualstudio.com/{project}/{repo}` or `dev.azure.com/{owner}/{project}/{repo}`
- * Microsoft is in the process of changing Azure DevOps to the latter form, so it may be safest to always specify both formats in your repo allowlist for each repository until the change is complete.
+
+* Accepts a comma separated list, ex. `definition1,definition2`
+* Format is `{hostname}/{owner}/{repo}`, ex. `github.com/runatlantis/atlantis`
+* `*` matches any characters, ex. `github.com/runatlantis/*` will match all repos in the runatlantis organization
+* An entry beginning with `!` negates it, ex. `github.com/foo/*,!github.com/foo/bar` will match all github repos in the `foo` owner *except* `bar`.
+* For Bitbucket Server: `{hostname}` is the domain without scheme and port, `{owner}` is the name of the project (not the key), and `{repo}` is the repo name
+ * User (not project) repositories take on the format: `{hostname}/{full name}/{repo}` (e.g., `bitbucket.example.com/Jane Doe/myatlantis` for username `jdoe` and full name `Jane Doe`, which is not very intuitive)
+* For Azure DevOps the allowlist takes one of two forms: `{owner}.visualstudio.com/{project}/{repo}` or `dev.azure.com/{owner}/{project}/{repo}`
+* Microsoft is in the process of changing Azure DevOps to the latter form, so it may be safest to always specify both formats in your repo allowlist for each repository until the change is complete.
Examples:
- * Allowlist `myorg/repo1` and `myorg/repo2` on `github.com`
- * `--repo-allowlist=github.com/myorg/repo1,github.com/myorg/repo2`
- * Allowlist all repos under `myorg` on `github.com`
- * `--repo-allowlist='github.com/myorg/*'`
- * Allowlist all repos under `myorg` on `github.com`, excluding `myorg/untrusted-repo`
- * `--repo-allowlist='github.com/myorg/*,!github.com/myorg/untrusted-repo'`
- * Allowlist all repos in my GitHub Enterprise installation
- * `--repo-allowlist='github.yourcompany.com/*'`
- * Allowlist all repos under `myorg` project `myproject` on Azure DevOps
- * `--repo-allowlist='myorg.visualstudio.com/myproject/*,dev.azure.com/myorg/myproject/*'`
- * Allowlist all repositories
- * `--repo-allowlist='*'`
+
+* Allowlist `myorg/repo1` and `myorg/repo2` on `github.com`
+ * `--repo-allowlist=github.com/myorg/repo1,github.com/myorg/repo2`
+* Allowlist all repos under `myorg` on `github.com`
+ * `--repo-allowlist='github.com/myorg/*'`
+* Allowlist all repos under `myorg` on `github.com`, excluding `myorg/untrusted-repo`
+ * `--repo-allowlist='github.com/myorg/*,!github.com/myorg/untrusted-repo'`
+* Allowlist all repos in my GitHub Enterprise installation
+ * `--repo-allowlist='github.yourcompany.com/*'`
+* Allowlist all repos under `myorg` project `myproject` on Azure DevOps
+ * `--repo-allowlist='myorg.visualstudio.com/myproject/*,dev.azure.com/myorg/myproject/*'`
+* Allowlist all repositories
+ * `--repo-allowlist='*'`
### `--repo-config`
+
```bash
atlantis server --repo-config="path/to/repos.yaml"
# or
ATLANTIS_REPO_CONFIG="path/to/repos.yaml"
```
+
Path to a YAML server-side repo config file. See [Server Side Repo Config](server-side-repo-config.md).
### `--repo-config-json`
+
```bash
atlantis server --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}'
# or
ATLANTIS_REPO_CONFIG_JSON='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}'
```
+
Specify server-side repo config as a JSON string. Useful if you don't want to write a config file to disk.
See [Server Side Repo Config](server-side-repo-config.md) for more details.
::: tip
If specifying a [Workflow](custom-workflows.md#reference), [step](custom-workflows.md#step)'s
can be specified as follows:
+
```json
{
"repos": [],
@@ -925,25 +1086,30 @@ This is useful when you have many projects and want to keep the pull request cle
}
}
```
+
:::
### `--restrict-file-list`
+
```bash
atlantis server --restrict-file-list
# or (recommended)
ATLANTIS_RESTRICT_FILE_LIST=true
```
+
`--restrict-file-list` will block plan requests from projects outside the files modified in the pull request.
This will not block plan requests with regex if using the `--enable-regexp-cmd` flag, in these cases commands
like `atlantis plan -p .*` will still work if used. normal commands will stil be blocked if necessary.
Defaults to `false`.
### `--silence-allowlist-errors`
+
```bash
atlantis server --silence-allowlist-errors
# or
ATLANTIS_SILENCE_ALLOWLIST_ERRORS=true
```
+
Some users use the `--repo-allowlist` flag to control which repos Atlantis
responds to. Normally, if Atlantis receives a pull request webhook from a repo not listed
in the allowlist, it will comment back with an error. This flag disables that commenting.
@@ -952,20 +1118,24 @@ This is useful when you have many projects and want to keep the pull request cle
at an organization level rather than on each repo.
### `--silence-fork-pr-errors`
+
```bash
atlantis server --silence-fork-pr-errors
# or
ATLANTIS_SILENCE_FORK_PR_ERRORS=true
```
+
Normally, if Atlantis receives a pull request webhook from a fork and --allow-fork-prs is not set,
it will comment back with an error. This flag disables that commenting.
### `--silence-no-projects`
+
```bash
atlantis server --silence-no-projects
# or
ATLANTIS_SILENCE_NO_PROJECTS=true
```
+
`--silence-no-projects` will tell Atlantis to ignore PRs if none of the modified files are part of a project defined in the `atlantis.yaml` file.
This flag ensures an Atlantis server only responds to its explicitly declared projects.
This has no effect if projects are undefined in the repo level `atlantis.yaml`.
@@ -975,78 +1145,96 @@ This is useful when you have many projects and want to keep the pull request cle
delegate work to each Atlantis server. Also useful when used with pre_workflow_hooks to dynamically generate an `atlantis.yaml` file.
### `--silence-vcs-status-no-plans`
+
```bash
atlantis server --silence-vcs-status-no-plans
# or
ATLANTIS_SILENCE_VCS_STATUS_NO_PLANS=true
```
+
`--silence-vcs-status-no-plans` will tell Atlantis to ignore setting VCS status on plans if none of the modified files are part of a project defined in the `atlantis.yaml` file.
### `--silence-vcs-status-no-projects`
+
```bash
atlantis server --silence-vcs-status-no-projects
# or
ATLANTIS_SILENCE_VCS_STATUS_NO_PROJECTS=true
```
+
`--silence-vcs-status-no-projects` will tell Atlantis to ignore setting VCS status on any command if none of the modified files are part of a project defined in the `atlantis.yaml` file.
### `--skip-clone-no-changes`
+
```bash
atlantis server --skip-clone-no-changes
# or
ATLANTIS_SKIP_CLONE_NO_CHANGES=true
```
+
`--skip-clone-no-changes` will skip cloning the repo during autoplan if there are no changes to Terraform projects. This will only apply for GitHub and GitLab and only for repos that have `atlantis.yaml` file. Defaults to `false`.
### `--slack-token`
+
```bash
atlantis server --slack-token=token
# or (recommended)
ATLANTIS_SLACK_TOKEN='token'
```
+
API token for Slack notifications. Slack is not fully supported. TODO: Slack docs.
### `--ssl-cert-file`
+
```bash
atlantis server --ssl-cert-file="/etc/ssl/certs/my-cert.crt"
# or
ATLANTIS_SSL_CERT_FILE="/etc/ssl/certs/my-cert.crt"
```
+
File containing x509 Certificate used for serving HTTPS.
If the cert is signed by a CA, the file should be the concatenation
of the server's certificate, any intermediates, and the CA's certificate.
### `--ssl-key-file`
+
```bash
atlantis server --ssl-key-file="/etc/ssl/private/my-cert.key"
# or
ATLANTIS_SSL_KEY_FILE="/etc/ssl/private/my-cert.key"
```
+
File containing x509 private key matching `--ssl-cert-file`.
### `--stats-namespace`
+
```bash
atlantis server --stats-namespace="myatlantis"
# or
ATLANTIS_STATS_NAMESPACE="myatlantis"
```
+
Namespace for emitting stats/metrics. See [stats](stats.md) section.
### `--tf-download`
+
```bash
atlantis server --tf-download=false
# or
ATLANTIS_TF_DOWNLOAD=false
```
+
Defaults to `true`. Allow Atlantis to list and download additional versions of Terraform.
Setting this to `false` can be useful in an air-gapped environment where a download mirror is not available.
### `--tf-download-url`
+
```bash
atlantis server --tf-download-url="https://releases.company.com"
# or
ATLANTIS_TF_DOWNLOAD_URL="https://releases.company.com"
```
+
An alternative URL to download Terraform versions if they are missing. Useful in an airgapped
environment where releases.hashicorp.com is not available. Directory structure of the custom
endpoint should match that of releases.hashicorp.com.
@@ -1054,106 +1242,128 @@ Setting this to `false` can be useful in an air-gapped environment where a downl
This has no impact if `--tf-download` is set to `false`.
### `--tfe-hostname`
+
```bash
atlantis server --tfe-hostname="my-terraform-enterprise.company.com"
# or
ATLANTIS_TFE_HOSTNAME="my-terraform-enterprise.company.com"
```
+
Hostname of your Terraform Enterprise installation to be used in conjunction with
`--tfe-token`. See [Terraform Cloud](terraform-cloud.md) for more details.
If using Terraform Cloud (i.e. you don't have your own Terraform Enterprise installation)
no need to set since it defaults to `app.terraform.io`.
### `--tfe-local-execution-mode`
+
```bash
atlantis server --tfe-local-execution-mode
# or
ATLANTIS_TFE_LOCAL_EXECUTION_MODE=true
```
+
Enable if you're using local execution mode (instead of TFE/C's remote execution mode). See [Terraform Cloud](terraform-cloud.md) for more details.
### `--tfe-token`
+
```bash
atlantis server --tfe-token="xxx.atlasv1.yyy"
# or (recommended)
ATLANTIS_TFE_TOKEN='xxx.atlasv1.yyy'
```
+
A token for Terraform Cloud/Terraform Enterprise integration. See [Terraform Cloud](terraform-cloud.md) for more details.
### `--use-tf-plugin-cache`
+
```bash
atlantis server --use-tf-plugin-cache=false
# or
ATLANTIS_USE_TF_PLUGIN_CACHE=false
```
+
Set to false if you want to disable terraform plugin cache.
This flag is useful when having multiple projects that need to run a plan and apply in the same PR to avoid the race condition of `plugin_cache_dir` concurrently, this is a terraform known issue, more info:
-- [plugin_cache_dir concurrently discussion](https://github.com/hashicorp/terraform/issues/31964)
-- [PR to improve the situation](https://github.com/hashicorp/terraform/pull/33479)
+* [plugin_cache_dir concurrently discussion](https://github.com/hashicorp/terraform/issues/31964)
+* [PR to improve the situation](https://github.com/hashicorp/terraform/pull/33479)
The effect of the race condition is more evident when using parallel configuration to run plan and apply, by disabling the use of plugin cache will impact in the performance when starting a new plan or apply, but in large atlantis deployments with multiple projects and shared modules the use of `--parallel_plan` and `--parallel_apply` is mandatory for an efficient managment of the PRs.
### `--var-file-allowlist`
+
```bash
atlantis server --var-file-allowlist='/path/to/tfvars/dir'
# or
ATLANTIS_VAR_FILE_ALLOWLIST='/path/to/tfvars/dir'
```
+
Comma-separated list of additional directory paths where [variable definition files](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files) can be read from.
The paths in this argument should be absolute paths. Relative paths and globbing are currently not supported.
If this argument is not provided, it defaults to Atlantis' data directory, determined by the `--data-dir` argument.
### `--vcs-status-name`
+
```bash
atlantis server --vcs-status-name="atlantis-dev"
# or
ATLANTIS_VCS_STATUS_NAME="atlantis-dev"
```
+
Name used to identify Atlantis when updating a pull request status. Defaults to `atlantis`.
This is useful when running multiple Atlantis servers against a single repository so you can
give each Atlantis server its own unique name to prevent the statuses clashing.
### `--web-basic-auth`
+
```bash
atlantis server --web-basic-auth
# or
ATLANTIS_WEB_BASIC_AUTH=true
```
+
Enable Basic Authentication on the Atlantis web service.
### `--web-password`
+
```bash
atlantis server --web-password="atlantis"
# or
ATLANTIS_WEB_PASSWORD="atlantis"
```
+
Password used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`.
### `--web-username`
+
```bash
atlantis server --web-username="atlantis"
# or
ATLANTIS_WEB_USERNAME="atlantis"
```
+
Username used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`.
### `--websocket-check-origin`
+
```bash
atlantis server --websocket-check-origin
# or
ATLANTIS_WEBSOCKET_CHECK_ORIGIN=true
```
+
Only allow websockets connection when they originate from the running Atlantis web server
### `--write-git-creds`
+
```bash
atlantis server --write-git-creds
# or
ATLANTIS_WRITE_GIT_CREDS=true
```
+
Write out a .git-credentials file with the provider user and token to allow
cloning private modules over HTTPS or SSH. See [here](https://git-scm.com/docs/git-credential-store) for more information.
@@ -1170,4 +1380,3 @@ The effect of the race condition is more evident when using parallel configurati
::: warning SECURITY WARNING
This does write secrets to disk and should only be enabled in a secure environment.
:::
-
diff --git a/runatlantis.io/docs/server-side-repo-config.md b/runatlantis.io/docs/server-side-repo-config.md
index 4ebbaba7e9..031df79fce 100644
--- a/runatlantis.io/docs/server-side-repo-config.md
+++ b/runatlantis.io/docs/server-side-repo-config.md
@@ -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` |
diff --git a/runatlantis.io/docs/stats.md b/runatlantis.io/docs/stats.md
index 39ef9f88f0..9c6073ab64 100644
--- a/runatlantis.io/docs/stats.md
+++ b/runatlantis.io/docs/stats.md
@@ -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.
:::
diff --git a/runatlantis.io/docs/streaming-logs.md b/runatlantis.io/docs/streaming-logs.md
index c066d47d47..df936c52f9 100644
--- a/runatlantis.io/docs/streaming-logs.md
+++ b/runatlantis.io/docs/streaming-logs.md
@@ -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.
:::
-
diff --git a/runatlantis.io/docs/terraform-cloud.md b/runatlantis.io/docs/terraform-cloud.md
index 1de4158ba7..2e3393d7dd 100644
--- a/runatlantis.io/docs/terraform-cloud.md
+++ b/runatlantis.io/docs/terraform-cloud.md
@@ -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.
:::
diff --git a/runatlantis.io/docs/terraform-versions.md b/runatlantis.io/docs/terraform-versions.md
index b38cebf9d7..321278d505 100644
--- a/runatlantis.io/docs/terraform-versions.md
+++ b/runatlantis.io/docs/terraform-versions.md
@@ -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
diff --git a/runatlantis.io/docs/troubleshooting-https.md b/runatlantis.io/docs/troubleshooting-https.md
index dc4c7a0541..f59058da1c 100644
--- a/runatlantis.io/docs/troubleshooting-https.md
+++ b/runatlantis.io/docs/troubleshooting-https.md
@@ -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).
-
-
diff --git a/runatlantis.io/docs/upgrading-atlantis-yaml.md b/runatlantis.io/docs/upgrading-atlantis-yaml.md
index 8b7f2cc384..37e20900e8 100644
--- a/runatlantis.io/docs/upgrading-atlantis-yaml.md
+++ b/runatlantis.io/docs/upgrading-atlantis-yaml.md
@@ -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
```
+
An example workflow using a custom run step
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:
diff --git a/runatlantis.io/docs/using-atlantis.md b/runatlantis.io/docs/using-atlantis.md
index 8abdddd4ad..61c06e1a21 100644
--- a/runatlantis.io/docs/using-atlantis.md
+++ b/runatlantis.io/docs/using-atlantis.md
@@ -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.
diff --git a/runatlantis.io/docs/using-slack-hooks.md b/runatlantis.io/docs/using-slack-hooks.md
index 8b32b1b92b..572b0857f8 100644
--- a/runatlantis.io/docs/using-slack-hooks.md
+++ b/runatlantis.io/docs/using-slack-hooks.md
@@ -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.
diff --git a/runatlantis.io/docs/webhook-secrets.md b/runatlantis.io/docs/webhook-secrets.md
index 050f548a83..4e2ab1a059 100644
--- a/runatlantis.io/docs/webhook-secrets.md
+++ b/runatlantis.io/docs/webhook-secrets.md
@@ -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
diff --git a/runatlantis.io/guide/test-drive.md b/runatlantis.io/guide/test-drive.md
index 08970ea110..8510f0a0e2 100644
--- a/runatlantis.io/guide/test-drive.md
+++ b/runatlantis.io/guide/test-drive.md
@@ -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).
diff --git a/runatlantis.io/guide/testing-locally.md b/runatlantis.io/guide/testing-locally.md
index 7e67065d66..104d40a942 100644
--- a/runatlantis.io/guide/testing-locally.md
+++ b/runatlantis.io/guide/testing-locally.md
@@ -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
+
### GitLab or GitLab Enterprise Webhook
+
### Bitbucket Cloud (bitbucket.org) Webhook
+
### Bitbucket Server (aka Stash) Webhook
+
### Gitea Webhook
+
-
## 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.
Expand
-
@@ -81,6 +91,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
Expand
-
@@ -102,6 +113,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
Expand
-
@@ -123,6 +135,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
Expand
-
@@ -140,6 +153,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
Expand
-
@@ -169,38 +183,45 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi