From 1cd51d749d51a16af032f84f552ab3790f169ec9 Mon Sep 17 00:00:00 2001 From: PePe Amengual <2208324+jamengual@users.noreply.github.com> Date: Tue, 12 Aug 2025 10:02:22 -0700 Subject: [PATCH] docs: add version annotations to server configuration and repo-level atlantis.yaml (#5631) --- atlantis-features-version-analysis.md | 328 +++ .../docs/repo-level-atlantis-yaml.md | 264 +-- runatlantis.io/docs/server-configuration.md | 2026 +++++++++-------- 3 files changed, 1486 insertions(+), 1132 deletions(-) create mode 100644 atlantis-features-version-analysis.md diff --git a/atlantis-features-version-analysis.md b/atlantis-features-version-analysis.md new file mode 100644 index 000000000..a660612f7 --- /dev/null +++ b/atlantis-features-version-analysis.md @@ -0,0 +1,328 @@ +# Atlantis Features Version Analysis + +This document provides a comprehensive analysis of Atlantis features and the versions when they were introduced, based on the changelog, merged PRs, and documentation. + +## Server Configuration Features + +### Core Features (v0.1.0+) + +These features have been available since the initial release or very early versions: + +- `--port` - Port to bind to (default: 4141) +- `--log-level` - Log level (debug|info|warn|error) +- `--gh-user` - GitHub username of API user +- `--gh-token` - GitHub token of API user +- `--gh-webhook-secret` - Secret used to validate GitHub webhooks +- `--repo-allowlist` - Allowlist of repositories (deprecated `--repo-whitelist` in v0.13.0) +- `--data-dir` - Directory where Atlantis stores its data +- `--atlantis-url` - URL that Atlantis is accessible from +- `--web-username` - Username for Basic Authentication +- `--web-password` - Password for Basic Authentication +- `--web-basic-auth` - Enable Basic Authentication on web service + +### v0.13.0 + +- `--allow-draft-prs` - Respond to pull requests from draft PRs + +### v0.15.0 + +- `--skip-clone-no-changes` - Skip cloning repo during autoplan if no changes to Terraform projects +- `--disable-autoplan` - Globally disable autoplanning + +### v0.16.0 + +- `--parallel-pool-size` - Max size of wait group for parallel plans/applies +- `--disable-apply-all` - Disable `atlantis apply` command (requires specific project/workspace/directory) + +### v0.16.1 + +- `--gh-app-slug` - GitHub App slug for identifying comments +- `--disable-repo-locking` - Stop Atlantis from locking projects/workspaces + +### v0.17.0 + +- `--enable-policy-checks` - Enable server-side policy checks with conftest +- `--autoplan-file-list` - Modify global list of files that trigger project planning +- `--silence-no-projects` - Silence Atlantis from responding to PRs when no projects +- `--enable-regexp-cmd` - Enable regex commands for project targeting +- `--disable-global-apply-lock` - Remove global apply lock button from UI +- `--automerge` - Automatically merge pull requests after successful applies + +### v0.18.0+ + +- `--default-tf-version` - Default Terraform version (introduced in v0.13.0, refined in later versions) +- `--tf-download` - Allow Atlantis to download Terraform versions +- `--tf-download-url` - Alternative URL for Terraform downloads + +### v0.19.0 + +- `--hide-prev-plan-comments` - Hide previous plan comments to declutter PRs + +### v0.19.5 + +- `--var-file-allowlist` - Restrict access to variable definition files + +### v0.20.0+ + +- `--gh-app-id` - GitHub App ID for installation-based authentication +- `--gh-app-key` - GitHub App private key +- `--gh-app-key-file` - Path to GitHub App private key file +- `--gh-app-installation-id` - Specific GitHub App installation ID + +### v0.21.0 + +- `--markdown-template-overrides-dir` - Directory for markdown template overrides + +### v0.22.0+ + +- `--parallel-plan` - Run plan operations in parallel +- `--parallel-apply` - Run apply operations in parallel +- `--abort-on-execution-order-fail` - Abort execution on failures + +### v0.23.0+ + +- `--enable-plan-queue` - Enable plan queue feature for queuing plan requests +- `--enable-lock-retry` - Enable automatic retry of lock acquisition +- `--lock-retry-delay` - Delay between lock retry attempts +- `--lock-retry-max-attempts` - Maximum lock retry attempts + +### v0.24.0+ + +- `--default-tf-distribution` - Default Terraform distribution (terraform/opentofu) +- `--terraform-cloud` - Terraform Cloud integration features + +### v0.25.0+ + +- `--enable-profiling-api` - Enable pprof endpoints for profiling +- `--enable-diff-markdown-format` - Format Terraform plan output for markdown-diff + +### v0.26.0+ + +- `--autoplan-modules` - Enable autoplanning when modules change +- `--autoplan-modules-from-projects` - Configure which projects to index for module changes + +### v0.27.0+ + +- `--autodiscover-mode` - Configure autodiscovery mode (auto|enabled|disabled) +- `--include-git-untracked-files` - Include untracked files in modified file list + +### v0.28.0+ + +- `--restrict-file-list` - Block plan requests from projects outside modified files +- `--silence-allowlist-errors` - Silence allowlist error comments +- `--silence-fork-pr-errors` - Silence fork PR error comments +- `--silence-vcs-status-no-plans` - Silence VCS status when no plans +- `--silence-vcs-status-no-projects` - Silence VCS status when no projects + +### v0.29.0+ + +- `--discard-approval-on-plan` - Discard approval if new plan executed +- `--emoji-reaction` - Emoji reaction for marking processed comments +- `--hide-unchanged-plan-comments` - Remove no-changes plan comments + +### v0.30.0+ + +- `--gh-allow-mergeable-bypass-apply` - Allow mergeable mode with required apply status check +- `--ignore-vcs-status-names` - Ignore VCS status names from other Atlantis services + +### v0.31.0+ + +- `--fail-on-pre-workflow-hook-error` - Fail if pre-workflow hooks error +- `--disable-markdown-folding` - Disable markdown folding in comments + +### v0.32.0+ + +- `--max-comments-per-command` - Limit comments published per command +- `--quiet-policy-checks` - Exclude policy check comments unless errors + +### v0.33.0+ + +- `--disable-unlock-label` - Stop unlocking PRs with specific label +- `--disable-autoplan-label` - Disable autoplanning on PRs with specific label + +### v0.34.0+ + +- `--allow-commands` - List of allowed commands to run +- `--allow-fork-prs` - Respond to pull requests from forks + +### v0.35.0+ + +- `--azuredevops-hostname` - Azure DevOps hostname support +- `--azuredevops-token` - Azure DevOps token +- `--azuredevops-user` - Azure DevOps username +- `--azuredevops-webhook-password` - Azure DevOps webhook password +- `--azuredevops-webhook-user` - Azure DevOps webhook username + +### v0.36.0+ + +- `--bitbucket-base-url` - Bitbucket Server base URL +- `--bitbucket-token` - Bitbucket app password +- `--bitbucket-user` - Bitbucket username +- `--bitbucket-webhook-secret` - Bitbucket webhook secret + +### v0.37.0+ + +- `--checkout-depth` - Number of commits to fetch from branch +- `--checkout-strategy` - How to check out pull requests (branch|merge) + +### v0.38.0+ + +- `--config` - YAML config file for flags +- `--repo-config` - Path to server-side repo config file +- `--repo-config-json` - Server-side repo config as JSON string + +### v0.39.0+ + +- `--gitea-base-url` - Gitea base URL +- `--gitea-token` - Gitea app password +- `--gitea-user` - Gitea username +- `--gitea-webhook-secret` - Gitea webhook secret +- `--gitea-page-size` - Number of items per page in Gitea responses + +### v0.40.0+ + +- `--gitlab-hostname` - GitLab Enterprise hostname +- `--gitlab-token` - GitLab token +- `--gitlab-user` - GitLab username +- `--gitlab-webhook-secret` - GitLab webhook secret +- `--gitlab-group-allowlist` - GitLab groups and permission pairs + +### v0.41.0+ + +- `--gh-team-allowlist` - GitHub teams and permission pairs +- `--gh-token-file` - GitHub token loaded from file + +### v0.42.0+ + +- `--executable-name` - Comment command trigger executable name +- `--vcs-status-name` - Name for identifying Atlantis in PR status + +### v0.43.0+ + +- `--stats-namespace` - Namespace for emitting stats/metrics +- `--slack-token` - API token for Slack notifications + +### v0.44.0+ + +- `--ssl-cert-file` - SSL certificate file for HTTPS +- `--ssl-key-file` - SSL private key file for HTTPS + +### v0.45.0+ + +- `--tfe-hostname` - Terraform Enterprise hostname +- `--tfe-token` - Terraform Cloud/Enterprise token +- `--tfe-local-execution-mode` - Enable local execution mode + +### v0.46.0+ + +- `--use-tf-plugin-cache` - Enable/disable Terraform plugin cache +- `--webhook-http-headers` - Additional headers for HTTP webhooks + +### v0.47.0+ + +- `--websocket-check-origin` - Only allow websockets from Atlantis web server +- `--write-git-creds` - Write .git-credentials file for private modules + +### v0.48.0+ + +- `--locking-db-type` - Locking database type (boltdb|redis) +- `--redis-host` - Redis hostname +- `--redis-port` - Redis port +- `--redis-password` - Redis password +- `--redis-db` - Redis database number +- `--redis-tls-enabled` - Enable TLS connection to Redis +- `--redis-insecure-skip-verify` - Skip Redis certificate verification + +## Repo-Level atlantis.yaml Features + +### Core Features (v0.1.0+) + +- `version` - Configuration version (required) +- `projects` - List of projects in the repo +- `workflows` - Custom workflows (restricted) + +### v0.15.0+ + +- `automerge` - Automatically merge PR when all plans applied +- `delete_source_branch_on_merge` - Delete source branch on merge + +### v0.17.0+ + +- `parallel_plan` - Run plans in parallel +- `parallel_apply` - Run applies in parallel +- `abort_on_execution_order_fail` - Abort on execution order failures + +### v0.18.0+ + +- `autodiscover` - Configure autodiscovery mode and ignore paths + +### v0.19.0+ + +- `allowed_regexp_prefixes` - Allowed regex prefixes for regex commands + +## Project-Level Features + +### Core Features (v0.1.0+) + +- `name` - Project name +- `dir` - Project directory +- `workspace` - Terraform workspace +- `terraform_version` - Specific Terraform version + +### v0.17.0+ + +- `execution_order_group` - Execution order group index +- `delete_source_branch_on_merge` - Delete source branch on merge +- `repo_locking` - Repository locking (deprecated) +- `repo_locks` - Repository locks configuration +- `custom_policy_check` - Enable custom policy check tools +- `autoplan` - Custom autoplan configuration +- `plan_requirements` - Requirements for plan command (restricted) +- `apply_requirements` - Requirements for apply command (restricted) +- `import_requirements` - Requirements for import command (restricted) +- `silence_pr_comments` - Silence PR comments for specific stages +- `workflow` - Custom workflow (restricted) + +### v0.20.0+ + +- `branch` - Regex matching projects by base branch +- `depends_on` - Project dependencies + +### v0.25.0+ + +- `terraform_distribution` - Terraform distribution (terraform/opentofu) + +## Autoplan Configuration + +### Core Features (v0.1.0+) + +- `enabled` - Whether autoplanning is enabled +- `when_modified` - File patterns that trigger autoplanning + +## RepoLocks Configuration + +### v0.17.0+ + +- `mode` - Repository lock mode (disabled|on_plan|on_apply) + +## Notes + +1. **Version Accuracy**: This analysis is based on the changelog, documentation, and code analysis. Some features may have been introduced in different versions than documented due to the changelog not being updated consistently. + +2. **Restricted Features**: Some features are marked as "restricted" and require server-side configuration to enable. + +3. **Deprecated Features**: Some features have been deprecated in favor of newer alternatives (e.g., `--repo-whitelist` → `--repo-allowlist`). + +4. **Missing Versions**: For some features, the exact introduction version could not be determined from the available documentation and changelog. These are marked with approximate version ranges. + +5. **Recent Features**: Features introduced after v0.23.0 may not be fully documented in the changelog as noted in the changelog header. + +## Recommendations + +1. **Update Documentation**: The documentation should be updated to include version information for each feature. + +2. **Enhance Changelog**: The changelog should be maintained more consistently to track feature introductions. + +3. **Version Tags**: Consider adding version tags to documentation sections to indicate when features were introduced. + +4. **Migration Guides**: Provide migration guides for deprecated features and breaking changes. diff --git a/runatlantis.io/docs/repo-level-atlantis-yaml.md b/runatlantis.io/docs/repo-level-atlantis-yaml.md index da7defd51..a3978c067 100644 --- a/runatlantis.io/docs/repo-level-atlantis-yaml.md +++ b/runatlantis.io/docs/repo-level-atlantis-yaml.md @@ -22,8 +22,8 @@ more details. **Notes:** -* By default, repo root `atlantis.yaml` file is used. -* You can change this behaviour by setting [Server Side Repo Config](server-side-repo-config.md) +- By default, repo root `atlantis.yaml` file is used. +- You can change this behaviour by setting [Server Side Repo Config](server-side-repo-config.md) ::: danger DANGER Atlantis uses the `atlantis.yaml` version from the pull request, similar to other @@ -53,40 +53,40 @@ manually configured project, the manually configured project will take precedenc ## Example Using All Keys ```yaml -version: 3 -automerge: true -autodiscover: +version: 3 +automerge: true +autodiscover: mode: auto ignore_paths: - some/path -delete_source_branch_on_merge: true -parallel_plan: true -parallel_apply: true -abort_on_execution_order_fail: true +delete_source_branch_on_merge: true +parallel_plan: true +parallel_apply: true +abort_on_execution_order_fail: true projects: -- name: my-project-name - branch: /main/ - dir: . - workspace: default - terraform_distribution: terraform - terraform_version: v0.11.0 - delete_source_branch_on_merge: true - repo_locking: true # deprecated: use repo_locks instead - repo_locks: +- name: my-project-name + branch: /main/ + dir: . + workspace: default + terraform_distribution: terraform + terraform_version: v0.11.0 + delete_source_branch_on_merge: true + repo_locking: true # deprecated: use repo_locks instead + repo_locks: mode: on_plan - custom_policy_check: false - autoplan: + custom_policy_check: false + autoplan: when_modified: ["*.tf", "../modules/**/*.tf", ".terraform.lock.hcl"] enabled: true - plan_requirements: [mergeable, approved, undiverged] - apply_requirements: [mergeable, approved, undiverged] - import_requirements: [mergeable, approved, undiverged] - silence_pr_comments: ["apply"] - execution_order_group: 1 - depends_on: + plan_requirements: [mergeable, approved, undiverged] + apply_requirements: [mergeable, approved, undiverged] + import_requirements: [mergeable, approved, undiverged] + silence_pr_comments: ["apply"] + execution_order_group: 1 + depends_on: - project-1 - workflow: myworkflow -workflows: + workflow: myworkflow +workflows: myworkflow: plan: steps: @@ -102,7 +102,7 @@ workflows: steps: - run: echo hi - apply -allowed_regexp_prefixes: +allowed_regexp_prefixes: - dev/ - staging/ ``` @@ -111,31 +111,31 @@ allowed_regexp_prefixes: ```yaml projects: - - &template - name: template - dir: template - workflow: custom - autoplan: - enabled: true - when_modified: - - "./terraform/modules/**/*.tf" - - "**/*.tf" - - ".terraform.lock.hcl" + - &template + name: template + dir: template + workflow: custom + autoplan: + enabled: true + when_modified: + - "./terraform/modules/**/*.tf" + - "**/*.tf" + - ".terraform.lock.hcl" - - <<: *template - name: ue1-prod-titan - dir: ./terraform/titan - workspace: ue1-prod + - <<: *template + name: ue1-prod-titan + dir: ./terraform/titan + workspace: ue1-prod - - <<: *template - name: ue1-stage-titan - dir: ./terraform/titan - workspace: ue1-stage + - <<: *template + name: ue1-stage-titan + dir: ./terraform/titan + workspace: ue1-stage - - <<: *template - name: ue1-dev-titan - dir: ./terraform/titan - workspace: ue1-dev + - <<: *template + name: ue1-dev-titan + dir: ./terraform/titan + workspace: ue1-dev ``` ## Auto generate projects @@ -161,9 +161,9 @@ grep -P 'backend[\s]+"s3"' **/*.tf | ```yaml version: 3 projects: -- dir: project1 - autoplan: - enabled: false + - dir: project1 + autoplan: + enabled: false ``` This will stop Atlantis automatically running plan when `project1/` is updated @@ -207,27 +207,27 @@ If you want Atlantis to plan `project1/` whenever any `.tf` files under `module1 ```yaml version: 3 projects: -- dir: project1 - autoplan: - when_modified: ["../modules/**/*.tf", "*.tf*", ".terraform.lock.hcl"] + - dir: project1 + autoplan: + when_modified: ["../modules/**/*.tf", "*.tf*", ".terraform.lock.hcl"] ``` Note: -* `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) -* The paths are relative to the project's directory. -* `when_modified` will be used by both automatic and manually run plans. -* `when_modified` will continue to work for manually run plans even when autoplan is disabled. +- `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) +- The paths are relative to the project's directory. +- `when_modified` will be used by both automatic and manually run plans. +- `when_modified` will continue to work for manually run plans even when autoplan is disabled. ### Supporting Terraform Workspaces ```yaml version: 3 projects: -- dir: project1 - workspace: staging -- dir: project1 - workspace: production + - dir: project1 + workspace: staging + - dir: project1 + workspace: production ``` With the above config, when Atlantis determines that the configuration for the `project1` dir has changed, @@ -273,8 +273,8 @@ by the `--default-tf-version` flag, then set the `terraform_distribution` key: ```yaml version: 3 projects: -- dir: project1 - terraform_distribution: opentofu + - dir: project1 + terraform_distribution: opentofu ``` Atlantis will automatically download and use this distribution. Valid values are `terraform` and `opentofu`. @@ -287,8 +287,8 @@ If you'd like to use a different version of Terraform than what is in Atlantis' ```yaml version: 3 projects: -- dir: project1 - terraform_version: 0.10.0 + - dir: project1 + terraform_version: 0.10.0 ``` Atlantis will automatically download and use this version. @@ -300,11 +300,11 @@ In this example, we only want to require `apply` approvals for the `production` ```yaml version: 3 projects: -- dir: staging -- dir: production - plan_requirements: [approved] - apply_requirements: [approved] - import_requirements: [approved] + - dir: staging + - dir: production + plan_requirements: [approved] + apply_requirements: [approved] + import_requirements: [approved] ``` :::warning @@ -318,10 +318,10 @@ to be allowed to set this key. See [Server-Side Repo Config Use Cases](server-si version: 3 abort_on_execution_order_fail: true projects: -- dir: project1 - execution_order_group: 2 -- dir: project2 - execution_order_group: 1 + - dir: project1 + execution_order_group: 2 + - dir: project2 + execution_order_group: 1 ``` With this config above, Atlantis runs planning/applying for project2 first, then for project1. @@ -341,29 +341,29 @@ The following configuration is an example of how to use execution order groups a ```yaml version: 3 projects: -- name: development - dir: . - autoplan: - when_modified: ["*.tf", "vars/development.tfvars"] - execution_order_group: 1 - workspace: development - workflow: infra -- name: staging - dir: . - autoplan: - when_modified: ["*.tf", "vars/staging.tfvars"] - depends_on: ["development"] - execution_order_group: 2 - workspace: staging - workflow: infra -- name: production - dir: . - autoplan: - when_modified: ["*.tf", "vars/production.tfvars"] - depends_on: ["staging"] - execution_order_group: 3 - workspace: production - workflow: infra + - name: development + dir: . + autoplan: + when_modified: ["*.tf", "vars/development.tfvars"] + execution_order_group: 1 + workspace: development + workflow: infra + - name: staging + dir: . + autoplan: + when_modified: ["*.tf", "vars/staging.tfvars"] + depends_on: ["development"] + execution_order_group: 2 + workspace: staging + workflow: infra + - name: production + dir: . + autoplan: + when_modified: ["*.tf", "vars/production.tfvars"] + depends_on: ["staging"] + execution_order_group: 3 + workspace: production + workflow: infra ``` the `depends_on` feature will make sure that `production` is not applied before `staging` for example. @@ -379,7 +379,7 @@ If there's one or more projects in the dependency list which is not in applied s ```yaml autodiscover: - mode: "auto" + mode: "auto" ``` The above is the default configuration for `autodiscover.mode`. When `autodiscover.mode` is auto, @@ -387,7 +387,7 @@ projects will be discovered only if the repo has no `projects` configured. ```yaml autodiscover: - mode: "disabled" + mode: "disabled" ``` With the config above, Atlantis will never try to discover projects, even when there are no @@ -396,7 +396,7 @@ See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-g ```yaml autodiscover: - mode: "enabled" + mode: "enabled" ``` With the config above, Atlantis will unconditionally try to discover projects based on modified_files, @@ -409,9 +409,9 @@ it's still desirable for Atlantis to plan/apply for projects not enumerated in t ```yaml autodiscover: - mode: "enabled" - ignore_paths: - - dir/* + mode: "enabled" + ignore_paths: + - dir/* ``` Autodiscover can also be configured to skip over directories that match a path glob (as defined [here](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4)) @@ -434,13 +434,13 @@ allowed_regexp_prefixes: ``` | Key | Type | Default | Required | Description | -|-------------------------------|--------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------| +| ----------------------------- | ------------------------------------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | version | int | none | **yes** | This key is required and must be set to `3`. | | automerge | bool | `false` | no | Automatically merges pull request when all plans are applied. | | delete_source_branch_on_merge | bool | `false` | no | Automatically deletes the source branch on merge. | | projects | array[[Project](repo-level-atlantis-yaml.md#project)] | `[]` | no | Lists the projects in this repo. | -| workflows
*(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. | +| workflows
_(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. | ### Project @@ -453,7 +453,7 @@ execution_order_group: 0 delete_source_branch_on_merge: false repo_locking: true # deprecated: use repo_locks instead repo_locks: - mode: on_plan + mode: on_plan custom_policy_check: false autoplan: terraform_version: 0.11.0 @@ -464,24 +464,24 @@ silence_pr_comments: ["apply"] workflow: myworkflow ``` -| Key | Type | Default | Required | Description | -|-----------------------------------------|-------------------------|-----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| name | string | none | maybe | Required if there is more than one project with the same `dir` and `workspace`. This project name can be used with the `-p` flag. | -| branch | string | none | no | Regex matching projects by the base branch of pull request (the branch the pull request is getting merged into). Only projects that match the PR's branch will be considered. By default, all branches are matched. | -| dir | string | none | **yes** | The directory of this project relative to the repo root. For example if the project was under `./project1` then use `project1`. Use `.` to indicate the repo root. | -| workspace | string | `"default"` | no | The [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces) for this project. Atlantis will switch to this workplace when planning/applying and will create it if it doesn't exist. | -| execution_order_group | int | `0` | no | Index of execution order group. Projects will be sort by this field before planning/applying. | -| delete_source_branch_on_merge | bool | `false` | no | Automatically deletes the source branch on merge. | -| repo_locking | bool | `true` | no | (deprecated) Get a repository lock in this project when plan. | -| repo_locks | [RepoLocks](#repolocks) | `mode: on_plan` | no | Get a repository lock in this project on plan or apply. See [RepoLocks](#repolocks) for more details. | -| custom_policy_check | bool | `false` | no | Enable using policy check tools other than Conftest | +| Key | Type | Default | Required | Description | +| --------------------------------------- | ----------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | string | none | maybe | Required if there is more than one project with the same `dir` and `workspace`. This project name can be used with the `-p` flag. | +| branch | string | none | no | Regex matching projects by the base branch of pull request (the branch the pull request is getting merged into). Only projects that match the PR's branch will be considered. By default, all branches are matched. | +| dir | string | none | **yes** | The directory of this project relative to the repo root. For example if the project was under `./project1` then use `project1`. Use `.` to indicate the repo root. | +| workspace | string | `"default"` | no | The [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces) for this project. Atlantis will switch to this workplace when planning/applying and will create it if it doesn't exist. | +| execution_order_group | int | `0` | no | Index of execution order group. Projects will be sort by this field before planning/applying. | +| delete_source_branch_on_merge | bool | `false` | no | Automatically deletes the source branch on merge. | +| repo_locking | bool | `true` | no | (deprecated) Get a repository lock in this project when plan. | +| repo_locks | [RepoLocks](#repolocks) | `mode: on_plan` | no | Get a repository lock in this project on plan or apply. See [RepoLocks](#repolocks) for more details. | +| 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. | +| 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. | | silence_pr_comments | array\[string\] | none | no | Silence PR comments from defined stages while preserving PR status checks. Supported values are: `plan`, `apply`. | -| workflow
*(restricted)* | string | none | no | A custom workflow. If not specified, Atlantis will use its default workflow. | +| workflow
_(restricted)_ | string | none | no | A custom workflow. If not specified, Atlantis will use its default workflow. | ::: tip A project represents a Terraform state. Typically, there is one state per directory and workspace however it's possible to @@ -496,10 +496,10 @@ 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. | +| 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. | ### RepoLocks @@ -508,5 +508,5 @@ mode: on_apply ``` | Key | Type | Default | Required | Description | -|------|--------|-----------|----------|---------------------------------------------------------------------------------------------------------------------------------------| +| ---- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | mode | `Mode` | `on_plan` | no | Whether or not repository locks are enabled for this project on plan or apply. Valid values are `disabled`, `on_plan` and `on_apply`. | diff --git a/runatlantis.io/docs/server-configuration.md b/runatlantis.io/docs/server-configuration.md index 142bb1df6..6fec8df0a 100644 --- a/runatlantis.io/docs/server-configuration.md +++ b/runatlantis.io/docs/server-configuration.md @@ -3,7 +3,7 @@ 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, a config file or a mix of the three. ## Environment Variables @@ -51,141 +51,141 @@ Values are chosen in this order: ## Flags -### `--allow-commands` +### `--allow-commands` - ```bash - atlantis server --allow-commands=version,plan,apply,unlock,approve_policies - # or - ATLANTIS_ALLOW_COMMANDS='version,plan,apply,unlock,approve_policies' - ``` +```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` +List of allowed commands to be run on the Atlantis server, Defaults to `version,plan,apply,unlock,approve_policies` - Notes: +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` +### `--allow-draft-prs` - ```bash - atlantis server --allow-draft-prs - # or - ATLANTIS_ALLOW_DRAFT_PRS=true - ``` +```bash +atlantis server --allow-draft-prs +# or +ATLANTIS_ALLOW_DRAFT_PRS=true +``` - Respond to pull requests from draft prs. Defaults to `false`. +Respond to pull requests from draft prs. Defaults to `false`. -### `--allow-fork-prs` +### `--allow-fork-prs` - ```bash - atlantis server --allow-fork-prs - # or - ATLANTIS_ALLOW_FORK_PRS=true - ``` +```bash +atlantis server --allow-fork-prs +# or +ATLANTIS_ALLOW_FORK_PRS=true +``` - Respond to pull requests from forks. Defaults to `false`. +Respond to pull requests from forks. Defaults to `false`. - :::warning SECURITY WARNING - Potentially dangerous to enable - because if attackers can create a pull request to your repo then they can cause Atlantis - to run arbitrary code. This can happen because - Atlantis will automatically run `terraform plan` - which can run arbitrary code if given a malicious Terraform configuration. - ::: +:::warning SECURITY WARNING +Potentially dangerous to enable +because if attackers can create a pull request to your repo then they can cause Atlantis +to run arbitrary code. This can happen because +Atlantis will automatically run `terraform plan` +which can run arbitrary code if given a malicious Terraform configuration. +::: -### `--api-secret` +### `--api-secret` - ```bash - atlantis server --api-secret="secret" - # or (recommended) - ATLANTIS_API_SECRET="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). +Required secret used to validate requests made to the [`/api/*` endpoints](api-endpoints.md). -### `--atlantis-url` +### `--atlantis-url` - ```bash - atlantis server --atlantis-url="https://my-domain.com:9090/basepath" - # or - ATLANTIS_ATLANTIS_URL=https://my-domain.com:9090/basepath - ``` +```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. +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: +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` +### `--autodiscover-mode` - ```bash - atlantis server --autodiscover-mode="" - # or - ATLANTIS_AUTODISCOVER_MODE="" - ``` +```bash +atlantis server --autodiscover-mode="" +# or +ATLANTIS_AUTODISCOVER_MODE="" +``` - Sets auto discover mode, default is `auto`. When set to `auto`, projects in a repo will be discovered by - Atlantis when there are no projects configured in the repo config. If one or more projects are defined - in the repo config then auto discovery will be completely disabled. +Sets auto discover mode, default is `auto`. When set to `auto`, projects in a repo will be discovered by +Atlantis when there are no projects configured in the repo config. If one or more projects are defined +in the repo config then auto discovery will be completely disabled. - When set to `enabled` projects will be discovered unconditionally. If an auto discovered project is already - defined in the projects section of the repo config, the project from the repo config will take precedence over - the auto discovered project. +When set to `enabled` projects will be discovered unconditionally. If an auto discovered project is already +defined in the projects section of the repo config, the project from the repo config will take precedence over +the auto discovered project. - When set to `disabled` projects will never be discovered, even if there are no projects configured in the repo config. +When set to `disabled` projects will never be discovered, even if there are no projects configured in the repo config. -### `--automerge` +### `--automerge` - ```bash - atlantis server --automerge - # or - ATLANTIS_AUTOMERGE=true - ``` +```bash +atlantis server --automerge +# or +ATLANTIS_AUTOMERGE=true +``` - Automatically merge pull requests after all plans have been successfully applied. - Defaults to `false`. See [Automerging](automerging.md) for more details. +Automatically merge pull requests after all plans have been successfully applied. +Defaults to `false`. See [Automerging](automerging.md) for more details. -### `--autoplan-file-list` +### `--autoplan-file-list` - ```bash - # NOTE: Use single quotes to avoid shell expansion of *. - atlantis server --autoplan-file-list='**/*.tf,project1/*.pkr.hcl' - # or - ATLANTIS_AUTOPLAN_FILE_LIST='**/*.tf,project1/*.pkr.hcl' - ``` +```bash +# NOTE: Use single quotes to avoid shell expansion of *. +atlantis server --autoplan-file-list='**/*.tf,project1/*.pkr.hcl' +# or +ATLANTIS_AUTOPLAN_FILE_LIST='**/*.tf,project1/*.pkr.hcl' +``` - List of file patterns that Atlantis will use to check if a directory contains modified files that should trigger project planning. +List of file patterns that Atlantis will use to check if a directory contains modified files that should trigger project planning. - Notes: +Notes: -* Accepts a comma separated list, ex. `pattern1,pattern2`. -* Patterns use the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) -* List of file patterns will be used by both automatic and manually run plans. -* When not set, defaults to all `.tf`, `.tfvars`, `.tfvars.json`, `terragrunt.hcl` and `.terraform.lock.hcl` files - (`--autoplan-file-list='**/*.tf,**/*.tfvars,**/*.tfvars.json,**/terragrunt.hcl,**/.terraform.lock.hcl'`). -* Setting `--autoplan-file-list` will override the defaults. You **must** add `**/*.tf` and other defaults if you want to include them. -* A custom [Workflow](repo-level-atlantis-yaml.md#configuring-planning) that uses autoplan `when_modified` will ignore this value. +- Accepts a comma separated list, ex. `pattern1,pattern2`. +- Patterns use the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) +- List of file patterns will be used by both automatic and manually run plans. +- When not set, defaults to all `.tf`, `.tfvars`, `.tfvars.json`, `terragrunt.hcl` and `.terraform.lock.hcl` files + (`--autoplan-file-list='**/*.tf,**/*.tfvars,**/*.tfvars.json,**/terragrunt.hcl,**/.terraform.lock.hcl'`). +- Setting `--autoplan-file-list` will override the defaults. You **must** add `**/*.tf` and other defaults if you want to include them. +- A custom [Workflow](repo-level-atlantis-yaml.md#configuring-planning) that uses autoplan `when_modified` will ignore this value. - Examples: +Examples: -* Autoplan when any `*.tf` or `*.tfvars` file is modified. - * `--autoplan-file-list='**/*.tf,**/*.tfvars'` -* Autoplan when any `*.tf` file is modified except in `project2/` directory - * `--autoplan-file-list='**/*.tf,!project2'` -* Autoplan when any `*.tf` files or `.yml` files in subfolder of `project1` is modified. - * `--autoplan-file-list='**/*.tf,project2/**/*.yml'` +- Autoplan when any `*.tf` or `*.tfvars` file is modified. + - `--autoplan-file-list='**/*.tf,**/*.tfvars'` +- Autoplan when any `*.tf` file is modified except in `project2/` directory + - `--autoplan-file-list='**/*.tf,!project2'` +- Autoplan when any `*.tf` files or `.yml` files in subfolder of `project1` is modified. + - `--autoplan-file-list='**/*.tf,project2/**/*.yml'` ::: warning NOTE By default, changes to modules will not trigger autoplanning. See the flags below. ::: -### `--autoplan-modules` +### `--autoplan-modules` ```bash atlantis server --autoplan-modules @@ -198,7 +198,7 @@ Included project are projects with files included by `--autoplan-file-list`. After tracing, Atlantis will plan any project that includes a changed module. This is equivalent to setting `--autoplan-modules-from-projects` to the value of `--autoplan-file-list`. See below. -### `--autoplan-modules-from-projects` +### `--autoplan-modules-from-projects` ```bash atlantis server --autoplan-modules-from-projects='**/init.tf' @@ -217,13 +217,13 @@ Current default is "" (disabled). Examples: -* `**/*.tf` - will index all projects that have a `.tf` file in their directory, and plan them whenever an in-repo module dependency has changed. -* `**/*.tf,!foo,!bar` - will index all projects containing `.tf` except `foo` and `bar` and plan them whenever an in-repo module dependency has changed. +- `**/*.tf` - will index all projects that have a `.tf` file in their directory, and plan them whenever an in-repo module dependency has changed. +- `**/*.tf,!foo,!bar` - will index all projects containing `.tf` except `foo` and `bar` and plan them whenever an in-repo module dependency has changed. This allows projects to opt-out of auto-planning when a module dependency changes. ::: warning NOTE Modules that are not selected by autoplan-file-list will not be indexed and dependant projects will not be planned. This -flag allows the *projects* to index to be selected, but the trigger for a plan must be a file in `autoplan-file-list`. +flag allows the _projects_ to index to be selected, but the trigger for a plan must be a file in `autoplan-file-list`. ::: ::: warning NOTE @@ -231,15 +231,15 @@ This flag overrides `--autoplan-modules`. If you wish to disable auto-planning o and set `--autoplan-modules` to `false`. ::: -### `--azuredevops-hostname` +### `--azuredevops-hostname` - ```bash - atlantis server --azuredevops-hostname="dev.azure.com" - # or - ATLANTIS_AZUREDEVOPS_HOSTNAME="dev.azure.com" - ``` +```bash +atlantis server --azuredevops-hostname="dev.azure.com" +# or +ATLANTIS_AZUREDEVOPS_HOSTNAME="dev.azure.com" +``` - Azure DevOps hostname to support cloud and self hosted instances. Defaults to `dev.azure.com`. +Azure DevOps hostname to support cloud and self hosted instances. Defaults to `dev.azure.com`. ::: warning COMPATIBILITY WARNING If you are affected by this change [docs](https://learn.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-devops-launch#administration) @@ -255,395 +255,415 @@ What to do if you have pending plans that were generated with a previous version Running an atlantis unlock from v0.35.0 on your current PRs will ignore the files on the `MYCompany` folder. On the next atlantis plan will use the `mycompany` folder and generate everything in the new folder name ::: -### `--azuredevops-token` +### `--azuredevops-token` - ```bash - atlantis server --azuredevops-token="RandomStringProducedByAzureDevOps" - # or (recommended) - ATLANTIS_AZUREDEVOPS_TOKEN="RandomStringProducedByAzureDevOps" - ``` +```bash +atlantis server --azuredevops-token="RandomStringProducedByAzureDevOps" +# or (recommended) +ATLANTIS_AZUREDEVOPS_TOKEN="RandomStringProducedByAzureDevOps" +``` - Azure DevOps token of API user. +Azure DevOps token of API user. -### `--azuredevops-user` +### `--azuredevops-user` - ```bash - atlantis server --azuredevops-user="username@example.com" - # or - ATLANTIS_AZUREDEVOPS_USER="username@example.com" - ``` +```bash +atlantis server --azuredevops-user="username@example.com" +# or +ATLANTIS_AZUREDEVOPS_USER="username@example.com" +``` - Azure DevOps username of API user. +Azure DevOps username of API user. -### `--azuredevops-webhook-password` +### `--azuredevops-webhook-password` - ```bash - atlantis server --azuredevops-webhook-password="password123" - # or (recommended) - ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD="password123" - ``` +```bash +atlantis server --azuredevops-webhook-password="password123" +# or (recommended) +ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD="password123" +``` - Azure DevOps basic authentication password for inbound webhooks (see - [docs](https://docs.microsoft.com/en-us/azure/devops/service-hooks/authorize?view=azure-devops)). +Azure DevOps basic authentication password for inbound webhooks (see +[docs](https://docs.microsoft.com/en-us/azure/devops/service-hooks/authorize?view=azure-devops)). - ::: warning SECURITY WARNING - If not specified, Atlantis won't be able to validate that the - incoming webhook call came from your Azure DevOps org. This means that an - attacker could spoof calls to Atlantis and cause it to perform malicious - actions. Should be specified via the `ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD` environment - variable. - ::: +::: warning SECURITY WARNING +If not specified, Atlantis won't be able to validate that the +incoming webhook call came from your Azure DevOps org. This means that an +attacker could spoof calls to Atlantis and cause it to perform malicious +actions. Should be specified via the `ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD` environment +variable. +::: -### `--azuredevops-webhook-user` +### `--azuredevops-webhook-user` - ```bash - atlantis server --azuredevops-webhook-user="username@example.com" - # or - ATLANTIS_AZUREDEVOPS_WEBHOOK_USER="username@example.com" - ``` +```bash +atlantis server --azuredevops-webhook-user="username@example.com" +# or +ATLANTIS_AZUREDEVOPS_WEBHOOK_USER="username@example.com" +``` - Azure DevOps basic authentication username for inbound webhooks. +Azure DevOps basic authentication username for inbound webhooks. -### `--bitbucket-base-url` +### `--bitbucket-base-url` - ```bash - atlantis server --bitbucket-base-url="http://bitbucket.corp:7990/basepath" - # or - ATLANTIS_BITBUCKET_BASE_URL="http://bitbucket.corp:7990/basepath" - ``` +```bash +atlantis server --bitbucket-base-url="http://bitbucket.corp:7990/basepath" +# or +ATLANTIS_BITBUCKET_BASE_URL="http://bitbucket.corp:7990/basepath" +``` - Base URL of Bitbucket Server (aka Stash) installation. Must include - `http://` or `https://`. If using Bitbucket Cloud (bitbucket.org), do not set. Defaults to - `https://api.bitbucket.org`. +Base URL of Bitbucket Server (aka Stash) installation. Must include +`http://` or `https://`. If using Bitbucket Cloud (bitbucket.org), do not set. Defaults to +`https://api.bitbucket.org`. -### `--bitbucket-token` +### `--bitbucket-token` - ```bash - atlantis server --bitbucket-token="token" - # or (recommended) - ATLANTIS_BITBUCKET_TOKEN="token" - ``` +```bash +atlantis server --bitbucket-token="token" +# or (recommended) +ATLANTIS_BITBUCKET_TOKEN="token" +``` - Bitbucket app password of API user. +Bitbucket app password of API user. -### `--bitbucket-user` +### `--bitbucket-user` - ```bash - atlantis server --bitbucket-user="myuser" - # or - ATLANTIS_BITBUCKET_USER="myuser" - ``` +```bash +atlantis server --bitbucket-user="myuser" +# or +ATLANTIS_BITBUCKET_USER="myuser" +``` - Bitbucket username of API user. +Bitbucket username of API user. -### `--bitbucket-webhook-secret` +### `--bitbucket-webhook-secret` - ```bash - atlantis server --bitbucket-webhook-secret="secret" - # or (recommended) - ATLANTIS_BITBUCKET_WEBHOOK_SECRET="secret" - ``` +```bash +atlantis server --bitbucket-webhook-secret="secret" +# or (recommended) +ATLANTIS_BITBUCKET_WEBHOOK_SECRET="secret" +``` - Secret used to validate Bitbucket webhooks. +Secret used to validate Bitbucket webhooks. - ::: warning SECURITY WARNING - If not specified, Atlantis won't be able to validate that the incoming webhook call came from Bitbucket. - This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. - ::: +::: warning SECURITY WARNING +If not specified, Atlantis won't be able to validate that the incoming webhook call came from Bitbucket. +This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. +::: -### `--checkout-depth` +### `--checkout-depth` - ```bash - atlantis server --checkout-depth=0 - # or - ATLANTIS_CHECKOUT_DEPTH=0 - ``` +```bash +atlantis server --checkout-depth=0 +# or +ATLANTIS_CHECKOUT_DEPTH=0 +``` - The number of commits to fetch from the branch. Used if `--checkout-strategy=merge` since the `--checkout-strategy=branch` (default) checkout strategy always defaults to a shallow clone using a depth of 1. - Defaults to `0`. See [Checkout Strategy](checkout-strategy.md) for more details. +The number of commits to fetch from the branch. Used if `--checkout-strategy=merge` since the `--checkout-strategy=branch` (default) checkout strategy always defaults to a shallow clone using a depth of 1. +Defaults to `0`. See [Checkout Strategy](checkout-strategy.md) for more details. -### `--checkout-strategy` +### `--checkout-strategy` - ```bash - atlantis server --checkout-strategy="" - # or - ATLANTIS_CHECKOUT_STRATEGY="" - ``` +```bash +atlantis server --checkout-strategy="" +# or +ATLANTIS_CHECKOUT_STRATEGY="" +``` - How to check out pull requests. Use either `branch` or `merge`. - Defaults to `branch`. See [Checkout Strategy](checkout-strategy.md) for more details. +How to check out pull requests. Use either `branch` or `merge`. +Defaults to `branch`. See [Checkout Strategy](checkout-strategy.md) for more details. -### `--config` +### `--config` - ```bash - atlantis server --config="my/config/file.yaml" - # or - ATLANTIS_CONFIG="my/config/file.yaml" - ``` +```bash +atlantis server --config="my/config/file.yaml" +# or +ATLANTIS_CONFIG="my/config/file.yaml" +``` - YAML config file where flags can also be set. See [Config File](#config-file) for more details. +YAML config file where flags can also be set. See [Config File](#config-file) for more details. -### `--data-dir` +### `--data-dir` - ```bash - atlantis server --data-dir="path/to/data/dir" - # or - ATLANTIS_DATA_DIR="path/to/data/dir" - ``` +```bash +atlantis server --data-dir="path/to/data/dir" +# or +ATLANTIS_DATA_DIR="path/to/data/dir" +``` - Directory where Atlantis will store its data. Will be created if it doesn't exist. - Defaults to `~/.atlantis`. Atlantis will store its database, checked out repos, Terraform plans and downloaded - Terraform binaries here. If Atlantis loses this directory, [locks](locking.md) - will be lost and unapplied plans will be lost. +Directory where Atlantis will store its data. Will be created if it doesn't exist. +Defaults to `~/.atlantis`. Atlantis will store its database, checked out repos, Terraform plans and downloaded +Terraform binaries here. If Atlantis loses this directory, [locks](locking.md) +will be lost and unapplied plans will be lost. - Note that the atlantis user is restricted to `~/.atlantis`. - If you set the `--data-dir` flag to a path outside of Atlantis its home directory, ensure that you grant the atlantis user the correct permissions. +Note that the atlantis user is restricted to `~/.atlantis`. +If you set the `--data-dir` flag to a path outside of Atlantis its home directory, ensure that you grant the atlantis user the correct permissions. -### `--default-tf-distribution` +### `--default-tf-distribution` - ```bash - atlantis server --default-tf-distribution="terraform" - # or - ATLANTIS_DEFAULT_TF_DISTRIBUTION="terraform" - ``` +```bash +atlantis server --default-tf-distribution="terraform" +# or +ATLANTIS_DEFAULT_TF_DISTRIBUTION="terraform" +``` - Which TF distribution to use. Can be set to `terraform` or `opentofu`. +Which TF distribution to use. Can be set to `terraform` or `opentofu`. -### `--default-tf-version` +### `--default-tf-version` - ```bash - atlantis server --default-tf-version="v0.12.31" - # or - ATLANTIS_DEFAULT_TF_VERSION="v0.12.31" - ``` +```bash +atlantis server --default-tf-version="v0.12.31" +# or +ATLANTIS_DEFAULT_TF_VERSION="v0.12.31" +``` - Terraform version to default to. Will download to `/bin/terraform` - if not in `PATH`. See [Terraform Versions](terraform-versions.md) for more details. +Terraform version to default to. Will download to `/bin/terraform` +if not in `PATH`. See [Terraform Versions](terraform-versions.md) for more details. -### `--disable-apply-all` +### `--disable-apply-all` - ```bash - atlantis server --disable-apply-all - # or - ATLANTIS_DISABLE_APPLY_ALL=true - ``` +```bash +atlantis server --disable-apply-all +# or +ATLANTIS_DISABLE_APPLY_ALL=true +``` - Disable `atlantis apply` command so a specific project/workspace/directory has to - be specified for applies. +Disable `atlantis apply` command so a specific project/workspace/directory has to +be specified for applies. -### `--disable-autoplan` +### `--disable-autoplan` - ```bash - atlantis server --disable-autoplan - # or - ATLANTIS_DISABLE_AUTOPLAN=true - ``` +```bash +atlantis server --disable-autoplan +# or +ATLANTIS_DISABLE_AUTOPLAN=true +``` - Disable atlantis auto planning. +Disable atlantis auto planning. -### `--disable-autoplan-label` +### `--disable-autoplan-label` - ```bash - atlantis server --disable-autoplan-label="no-autoplan" - # or - ATLANTIS_DISABLE_AUTOPLAN_LABEL="no-autoplan" - ``` +```bash +atlantis server --disable-autoplan-label="no-autoplan" +# or +ATLANTIS_DISABLE_AUTOPLAN_LABEL="no-autoplan" +``` - Disable atlantis auto planning only on pull requests with the specified label. +Disable atlantis auto planning only on pull requests with the specified label. - If `disable-autoplan` property is `true`, this flag has no effect. +If `disable-autoplan` property is `true`, this flag has no effect. -### `--disable-global-apply-lock` +### `--disable-global-apply-lock` - ```bash - atlantis server --disable-global-apply-lock - # or - ATLANTIS_DISABLE_GLOBAL_APPLY_LOCK=true - ``` +```bash +atlantis server --disable-global-apply-lock +# or +ATLANTIS_DISABLE_GLOBAL_APPLY_LOCK=true +``` - If true, removes button in the UI that allows users to globally disable apply commands. +If true, removes button in the UI that allows users to globally disable apply commands. -### `--disable-markdown-folding` +### `--disable-markdown-folding` - ```bash - atlantis server --disable-markdown-folding - # or - ATLANTIS_DISABLE_MARKDOWN_FOLDING=true - ``` +```bash +atlantis server --disable-markdown-folding +# or +ATLANTIS_DISABLE_MARKDOWN_FOLDING=true +``` - Disable folding in markdown output using the `
` html tag. +Disable folding in markdown output using the `
` html tag. -### `--disable-repo-locking` +### `--disable-repo-locking` - ```bash - atlantis server --disable-repo-locking - # or - ATLANTIS_DISABLE_REPO_LOCKING=true - ``` +```bash +atlantis server --disable-repo-locking +# or +ATLANTIS_DISABLE_REPO_LOCKING=true +``` - Stops atlantis from locking projects and or workspaces when running terraform. +Stops atlantis from locking projects and or workspaces when running terraform. -### `--disable-unlock-label` +### `--disable-unlock-label` - ```bash - atlantis server --disable-unlock-label do-not-unlock - # or - ATLANTIS_DISABLE_UNLOCK_LABEL="do-not-unlock" - ``` +```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). +Stops atlantis from unlocking a pull request with this label. Defaults to "" (feature disabled). -### `--discard-approval-on-plan` +### `--discard-approval-on-plan` - ```bash - atlantis server --discard-approval-on-plan - # or - ATLANTIS_DISCARD_APPROVAL_ON_PLAN=true - ``` +```bash +atlantis server --discard-approval-on-plan +# or +ATLANTIS_DISCARD_APPROVAL_ON_PLAN=true +``` - If set, discard approval if a new plan has been executed. Currently only supported on GitHub and GitLab. For GitLab a bot, group or project token is required for this feature. - Reference: [reset-approvals-of-a-merge-request](https://docs.gitlab.com/api/merge_request_approvals/#reset-approvals-of-a-merge-request) +If set, discard approval if a new plan has been executed. Currently only supported on GitHub and GitLab. For GitLab a bot, group or project token is required for this feature. + Reference: [reset-approvals-of-a-merge-request](https://docs.gitlab.com/api/merge_request_approvals/#reset-approvals-of-a-merge-request) -### `--emoji-reaction` +### `--emoji-reaction` - ```bash - atlantis server --emoji-reaction eyes - # or - ATLANTIS_EMOJI_REACTION=eyes - ``` +```bash +atlantis server --emoji-reaction eyes +# or +ATLANTIS_EMOJI_REACTION=eyes +``` - The emoji reaction to use for marking processed comments. Currently supported on Azure DevOps, GitHub and GitLab. If not specified, Atlantis will not use an emoji reaction. - Defaults to "" (empty string). +The emoji reaction to use for marking processed comments. Currently supported on Azure DevOps, GitHub and GitLab. If not specified, Atlantis will not use an emoji reaction. +Defaults to "" (empty string). - ::: warning NOTE - Each VCS provider supports a different list of emojis: - -* [Github](https://docs.github.com/en/rest/reactions/reactions?apiVersion=2022-11-28#about-reactions) -* [Gitlab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/fixtures/emojis/digests.json) -* [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#emoji) +::: warning NOTE +Each VCS provider supports a different list of emojis: - ::: +- [Github](https://docs.github.com/en/rest/reactions/reactions?apiVersion=2022-11-28#about-reactions) +- [Gitlab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/fixtures/emojis/digests.json) +- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#emoji) -### `--enable-diff-markdown-format` + ::: - ```bash - atlantis server --enable-diff-markdown-format - # or - ATLANTIS_ENABLE_DIFF_MARKDOWN_FORMAT=true - ``` +### `--enable-diff-markdown-format` - Enable Atlantis to format Terraform plan output into a markdown-diff friendly format for color-coding purposes. +```bash +atlantis server --enable-diff-markdown-format +# or +ATLANTIS_ENABLE_DIFF_MARKDOWN_FORMAT=true +``` - Useful to enable for use with GitHub. +Enable Atlantis to format Terraform plan output into a markdown-diff friendly format for color-coding purposes. -### `--enable-policy-checks` +Useful to enable for use with GitHub. - ```bash - atlantis server --enable-policy-checks - # or - ATLANTIS_ENABLE_POLICY_CHECKS=true - ``` +### `--enable-lock-retry` - 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). +```bash +atlantis server --enable-lock-retry +# or +ATLANTIS_ENABLE_LOCK_RETRY=true +``` -### `--enable-profiling-api` +Enable automatic retry of lock acquisition. When enabled, Atlantis will retry acquiring a lock if it is busy. Defaults to `false`. - ```bash - atlantis server --enable-profiling-api - # or - ATLANTIS_ENABLE_PROFILING_API=true - ``` +### `--enable-plan-queue` - Enable [`net/http/pprof`](https://pkg.go.dev/net/http/pprof) endpoints for [continuous profiling](https://grafana.com/docs/pyroscope/latest/introduction/continuous-profiling/) of resources used by the server. See [profiling Go programs](https://go.dev/blog/pprof) for more information. +```bash +atlantis server --enable-plan-queue +# or +ATLANTIS_ENABLE_PLAN_QUEUE=true +``` -### `--enable-regexp-cmd` +Enable the plan queue feature. When enabled, plan requests are queued if a lock is unavailable, rather than failing immediately. Defaults to `false`. - ```bash - atlantis server --enable-regexp-cmd - # or - ATLANTIS_ENABLE_REGEXP_CMD=true - ``` +### `--enable-policy-checks` - Enable Atlantis to use regular expressions to run plan/apply commands against defined project names when `-p` flag is passed with it. +```bash +atlantis server --enable-policy-checks +# or +ATLANTIS_ENABLE_POLICY_CHECKS=true +``` - This can be used to run all defined projects (with the `name` key) in `atlantis.yaml` using `atlantis plan -p .*`. +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). - The flag will only allow the regexes listed in the [`allowed_regexp_prefixes`](repo-level-atlantis-yaml.md#reference) key defined in the repo `atlantis.yaml` file. If the key is undefined, its value defaults to `[]` which will allow any regex. +### `--enable-profiling-api` - This will not work with `-d` yet and to use `-p` the repo projects must be defined in the repo `atlantis.yaml` file. +```bash +atlantis server --enable-profiling-api +# or +ATLANTIS_ENABLE_PROFILING_API=true +``` - This will bypass `--restrict-file-list` if regex is used, normal commands will still be blocked if necessary. +Enable [`net/http/pprof`](https://pkg.go.dev/net/http/pprof) endpoints for [continuous profiling](https://grafana.com/docs/pyroscope/latest/introduction/continuous-profiling/) of resources used by the server. See [profiling Go programs](https://go.dev/blog/pprof) for more information. - ::: warning SECURITY WARNING - It's not supposed to be used with `--disable-apply-all`. - The command `atlantis apply -p .*` will bypass the restriction and run apply on every projects. - ::: +### `--enable-regexp-cmd` -### `--executable-name` +```bash +atlantis server --enable-regexp-cmd +# or +ATLANTIS_ENABLE_REGEXP_CMD=true +``` - ```bash - atlantis server --executable-name="atlantis" - # or - ATLANTIS_EXECUTABLE_NAME="atlantis" - ``` +Enable Atlantis to use regular expressions to run plan/apply commands against defined project names when `-p` flag is passed with it. - Comment command trigger executable name. Defaults to `atlantis`. +This can be used to run all defined projects (with the `name` key) in `atlantis.yaml` using `atlantis plan -p .*`. - This is useful when running multiple Atlantis servers against a single repository. +The flag will only allow the regexes listed in the [`allowed_regexp_prefixes`](repo-level-atlantis-yaml.md#reference) key defined in the repo `atlantis.yaml` file. If the key is undefined, its value defaults to `[]` which will allow any regex. -### `--fail-on-pre-workflow-hook-error` +This will not work with `-d` yet and to use `-p` the repo projects must be defined in the repo `atlantis.yaml` file. - ```bash - atlantis server --fail-on-pre-workflow-hook-error - # or - ATLANTIS_FAIL_ON_PRE_WORKFLOW_HOOK_ERROR=true - ``` +This will bypass `--restrict-file-list` if regex is used, normal commands will still be blocked if necessary. - Fail and do not run the requested Atlantis command if any of the pre workflow hooks error. +::: warning SECURITY WARNING +It's not supposed to be used with `--disable-apply-all`. +The command `atlantis apply -p .*` will bypass the restriction and run apply on every projects. +::: -### `--gh-allow-mergeable-bypass-apply` +### `--executable-name` - ```bash - atlantis server --gh-allow-mergeable-bypass-apply - # or - ATLANTIS_GH_ALLOW_MERGEABLE_BYPASS_APPLY=true - ``` +```bash +atlantis server --executable-name="atlantis" +# or +ATLANTIS_EXECUTABLE_NAME="atlantis" +``` - Feature flag to enable ability to use `mergeable` mode with required apply status check. +Comment command trigger executable name. Defaults to `atlantis`. -### `--gh-app-id` +This is useful when running multiple Atlantis servers against a single repository. - ```bash - atlantis server --gh-app-id="00000" - # or - ATLANTIS_GH_APP_ID="00000" - ``` +### `--fail-on-pre-workflow-hook-error` - GitHub app ID. If set, GitHub authentication will be performed as [an installation](https://docs.github.com/en/rest/apps/installations). +```bash +atlantis server --fail-on-pre-workflow-hook-error +# or +ATLANTIS_FAIL_ON_PRE_WORKFLOW_HOOK_ERROR=true +``` - ::: tip - A GitHub app can be created by starting Atlantis first, then pointing your browser at +Fail and do not run the requested Atlantis command if any of the pre workflow hooks error. - ```shell - $(hostname)/github-app/setup - ``` +### `--gh-allow-mergeable-bypass-apply` - You'll be redirected to GitHub to create a new app, and will then be redirected to +```bash +atlantis server --gh-allow-mergeable-bypass-apply +# or +ATLANTIS_GH_ALLOW_MERGEABLE_BYPASS_APPLY=true +``` - ```shell - $(hostname)/github-app/exchange-code?code=some-code - ``` +Feature flag to enable ability to use `mergeable` mode with required apply status check. - After which Atlantis will display your new app's credentials: your app's ID, its generated `--gh-webhook-secret` and the contents of the file for `--gh-app-key-file`. Update your Atlantis config accordingly, and restart the server. - ::: +### `--gh-app-id` -### `--gh-app-installation-id` +```bash +atlantis server --gh-app-id="00000" +# or +ATLANTIS_GH_APP_ID="00000" +``` - ```bash - atlantis server --gh-app-installation-id="123" - # or - ATLANTIS_GH_APP_INSTALLATION_ID="123" - ``` +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 +``` + +After which Atlantis will display your new app's credentials: your app's ID, its generated `--gh-webhook-secret` and the contents of the file for `--gh-app-key-file`. Update your Atlantis config accordingly, and restart the server. +::: + +### `--gh-app-installation-id` + +```bash +atlantis server --gh-app-installation-id="123" +# or +ATLANTIS_GH_APP_INSTALLATION_ID="123" +``` The installation ID of a specific instance of a GitHub application. Normally this value is derived by querying GitHub for the list of installations of the ID supplied via `--gh-app-id` and selecting @@ -652,872 +672,878 @@ instances of Atlantis but you want to use a single already-installed GitHub app you are running a proxy as your single GitHub application that will proxy to an appropriate Atlantis instance based on the organization or user that triggered the webhook. -### `--gh-app-key` +### `--gh-app-key` - ```bash - atlantis server --gh-app-key="-----BEGIN RSA PRIVATE KEY-----(...)" - # or - ATLANTIS_GH_APP_KEY="-----BEGIN RSA PRIVATE 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. +The PEM encoded private key for the GitHub App. - ::: warning SECURITY WARNING - The contents of the private key will be visible by anyone that can run `ps` or look at the shell history of the machine where Atlantis is running. Use `--gh-app-key-file` to mitigate that risk. - ::: +::: warning SECURITY WARNING +The contents of the private key will be visible by anyone that can run `ps` or look at the shell history of the machine where Atlantis is running. Use `--gh-app-key-file` to mitigate that risk. +::: -### `--gh-app-key-file` +### `--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" - ``` +```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). +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` +### `--gh-app-slug` - ```bash - atlantis server --gh-app-slug="myappslug" - # or - ATLANTIS_GH_APP_SLUG="myappslug" - ``` +```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/`. +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` +### `--gh-hostname` - ```bash - atlantis server --gh-hostname="my.github.enterprise.com" - # or - ATLANTIS_GH_HOSTNAME="my.github.enterprise.com" - ``` +```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`. +Hostname of your GitHub Enterprise installation. If using [GitHub.com](https://github.com), +don't set. Defaults to `github.com`. -### `--gh-org` +### `--gh-org` - ```bash - atlantis server --gh-org="myorgname" - # or - ATLANTIS_GH_ORG="myorgname" - ``` +```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. +GitHub organization name. Set to enable creating a private GitHub app for this organization. -### `--gh-team-allowlist` +### `--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" - ``` +```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.35.0 and later, the GitHub team name can only be a slug because it is immutable. +In versions v0.35.0 and later, the GitHub team name can only be a slug because it is immutable. - In versions between v0.21.0 and v0.34.0, the GitHub team name can be a name or a slug. +In versions between v0.21.0 and v0.34.0, 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. +In versions v0.20.1 and below, the Github team name required the case sensitive team name. - Comma-separated list of GitHub teams and permission pairs. +Comma-separated list of GitHub teams and permission pairs. - By default, any team can plan and apply. +By default, any team can plan and apply. -### `--gh-token` +### `--gh-token` - ```bash - atlantis server --gh-token="token" - # or (recommended) - ATLANTIS_GH_TOKEN="token" - ``` +```bash +atlantis server --gh-token="token" +# or (recommended) +ATLANTIS_GH_TOKEN="token" +``` - GitHub token of API user. +GitHub token of API user. -### `--gh-token-file` +### `--gh-token-file` - ```bash - atlantis server --gh-token-file="/path/to/token" - # or - ATLANTIS_GH_TOKEN_FILE="/path/to/token" - ``` +```bash +atlantis server --gh-token-file="/path/to/token" +# or +ATLANTIS_GH_TOKEN_FILE="/path/to/token" +``` - GitHub token of API user. The token is loaded from disk regularly to allow for rotation of the token without the need to restart the Atlantis server. +GitHub token of API user. The token is loaded from disk regularly to allow for rotation of the token without the need to restart the Atlantis server. -### `--gh-user` +### `--gh-user` - ```bash - atlantis server --gh-user="myuser" - # or - ATLANTIS_GH_USER="myuser" - ``` +```bash +atlantis server --gh-user="myuser" +# or +ATLANTIS_GH_USER="myuser" +``` - GitHub username of API user. This user is also used by the flag `--hide-user-plan-comments` and will need to be updated if migrating to github EMU. +GitHub username of API user. This user is also used by the flag `--hide-user-plan-comments` and will need to be updated if migrating to github EMU. -### `--gh-webhook-secret` +### `--gh-webhook-secret` - ```bash - atlantis server --gh-webhook-secret="secret" - # or (recommended) - ATLANTIS_GH_WEBHOOK_SECRET="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)). +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 - If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitHub. - This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. - ::: +::: warning SECURITY WARNING +If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitHub. +This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. +::: -### `--gitea-base-url` +### `--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" - ``` +```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. +Base URL of Gitea installation. Must include `http://` or `https://`. Defaults to `https://gitea.com` if left empty/absent. -### `--gitea-page-size` +### `--gitea-page-size` - ```bash - atlantis server --gitea-page-size=30 - # or (recommended) - ATLANTIS_GITEA_PAGE_SIZE=30 - ``` +```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. +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 - ::: +::: 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 +::: -### `--gitea-token` +### `--gitea-token` - ```bash - atlantis server --gitea-token="token" - # or (recommended) - ATLANTIS_GITEA_TOKEN="token" - ``` +```bash +atlantis server --gitea-token="token" +# or (recommended) +ATLANTIS_GITEA_TOKEN="token" +``` - Gitea app password of API user. +Gitea app password of API user. -### `--gitea-user` +### `--gitea-user` - ```bash - atlantis server --gitea-user="myuser" - # or - ATLANTIS_GITEA_USER="myuser" - ``` +```bash +atlantis server --gitea-user="myuser" +# or +ATLANTIS_GITEA_USER="myuser" +``` - Gitea username of API user. +Gitea username of API user. -### `--gitea-webhook-secret` +### `--gitea-webhook-secret` - ```bash - atlantis server --gitea-webhook-secret="secret" - # or (recommended) - ATLANTIS_GITEA_WEBHOOK_SECRET="secret" - ``` +```bash +atlantis server --gitea-webhook-secret="secret" +# or (recommended) +ATLANTIS_GITEA_WEBHOOK_SECRET="secret" +``` - Secret used to validate Gitea webhooks. +Secret used to validate Gitea webhooks. - ::: warning SECURITY WARNING - If not specified, Atlantis won't be able to validate that the incoming webhook call came from Gitea. - This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. - ::: +::: warning SECURITY WARNING +If not specified, Atlantis won't be able to validate that the incoming webhook call came from Gitea. +This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. +::: -### `--gitlab-group-allowlist` +### `--gitlab-group-allowlist` - ```bash - atlantis server --gitlab-group-allowlist="myorg/mygroup:plan, myorg/secteam:apply, myorg/devops:apply, myorg/devops:import" - # or - ATLANTIS_GITLAB_GROUP_ALLOWLIST="myorg/mygroup:plan, myorg/secteam:apply, myorg/devops:apply, myorg/devops:import" - ``` +```bash +atlantis server --gitlab-group-allowlist="myorg/mygroup:plan, myorg/secteam:apply, myorg/devops:apply, myorg/devops:import" +# or +ATLANTIS_GITLAB_GROUP_ALLOWLIST="myorg/mygroup:plan, myorg/secteam:apply, myorg/devops:apply, myorg/devops:import" +``` - Comma-separated list of GitLab groups and permission pairs. +Comma-separated list of GitLab groups and permission pairs. - By default, any group can plan and apply. +By default, any group can plan and apply. - ::: warning NOTE - Atlantis needs to be able to view the listed group members, inaccessible or non-existent groups are silently ignored. +::: warning NOTE +Atlantis needs to be able to view the listed group members, inaccessible or non-existent groups are silently ignored. -### `--gitlab-hostname` +### `--gitlab-hostname` - ```bash - atlantis server --gitlab-hostname="my.gitlab.enterprise.com" - # or - ATLANTIS_GITLAB_HOSTNAME="my.gitlab.enterprise.com" - ``` +```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`. +Hostname of your GitLab Enterprise installation. If using [Gitlab.com](https://gitlab.com), +don't set. Defaults to `gitlab.com`. -### `--gitlab-token` +### `--gitlab-token` - ```bash - atlantis server --gitlab-token="token" - # or (recommended) - ATLANTIS_GITLAB_TOKEN="token" - ``` +```bash +atlantis server --gitlab-token="token" +# or (recommended) +ATLANTIS_GITLAB_TOKEN="token" +``` - GitLab token of API user. +GitLab token of API user. -### `--gitlab-user` +### `--gitlab-user` - ```bash - atlantis server --gitlab-user="myuser" - # or - ATLANTIS_GITLAB_USER="myuser" - ``` +```bash +atlantis server --gitlab-user="myuser" +# or +ATLANTIS_GITLAB_USER="myuser" +``` - GitLab username of API user. +GitLab username of API user. -### `--gitlab-webhook-secret` +### `--gitlab-webhook-secret` - ```bash - atlantis server --gitlab-webhook-secret="secret" - # or (recommended) - ATLANTIS_GITLAB_WEBHOOK_SECRET="secret" - ``` +```bash +atlantis server --gitlab-webhook-secret="secret" +# or (recommended) +ATLANTIS_GITLAB_WEBHOOK_SECRET="secret" +``` - Secret used to validate GitLab webhooks. +Secret used to validate GitLab webhooks. - ::: warning SECURITY WARNING - If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitLab. - This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. - ::: +::: warning SECURITY WARNING +If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitLab. +This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. +::: -### `--help` +### `--help` - ```bash - atlantis server --help - ``` +```bash +atlantis server --help +``` - View help. +View help. -### `--hide-prev-plan-comments` +### `--hide-prev-plan-comments` - ```bash - atlantis server --hide-prev-plan-comments - # or - ATLANTIS_HIDE_PREV_PLAN_COMMENTS=true - ``` +```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 and Bitbucket currently and is not enabled by default. - - For Bitbucket, the comments are deleted rather than hidden as Bitbucket does not support hiding comments. - - For GitHub, ensure the `--gh-user` is set appropriately or comments will not be hidden. +Hide previous plan comments to declutter PRs. This is only supported in +GitHub and GitLab and Bitbucket currently and is not enabled by default. - When using the GitHub App, you need to set `--gh-app-slug` to enable this feature. - -### `--hide-unchanged-plan-comments` +For Bitbucket, the comments are deleted rather than hidden as Bitbucket does not support hiding comments. - ```bash - atlantis server --hide-unchanged-plan-comments - # or - ATLANTIS_HIDE_UNCHANGED_PLAN_COMMENTS=true - ``` +For GitHub, ensure the `--gh-user` is set appropriately or comments will not be hidden. + +When using the 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. -### `--ignore-vcs-status-names` +### `--ignore-vcs-status-names` - ```bash - atlantis server --ignore-vcs-status-names="status1,status2" - # or - ATLANTIS_IGNORE_VCS_STATUS_NAMES=status1,status2 - ``` +```bash +atlantis server --ignore-vcs-status-names="status1,status2" +# or +ATLANTIS_IGNORE_VCS_STATUS_NAMES=status1,status2 +``` - Comma separated list of VCS status names from other atlantis services. - When `gh-allow-mergeable-bypass-apply` is true, will ignore status checks - (e.g. `status1/plan`, `status1/apply`, `status2/plan`, `status2/apply`) - from other Atlantis services when checking if the PR is mergeable. - Currently only implemented for GitHub. +Comma separated list of VCS status names from other atlantis services. +When `gh-allow-mergeable-bypass-apply` is true, will ignore status checks +(e.g. `status1/plan`, `status1/apply`, `status2/plan`, `status2/apply`) +from other Atlantis services when checking if the PR is mergeable. +Currently only implemented for GitHub. -### `--include-git-untracked-files` +### `--include-git-untracked-files` - ```bash - atlantis server --include-git-untracked-files - # or - ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true - ``` +```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. +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` +### `--lock-retry-delay` - ```bash - atlantis server --locking-db-type="" - # or - ATLANTIS_LOCKING_DB_TYPE="" - ``` +```bash +atlantis server --lock-retry-delay=5 +# or +ATLANTIS_LOCK_RETRY_DELAY=5 +``` - The locking database type to use for storing plan and apply locks. Defaults to `boltdb`. +Delay in seconds between lock retry attempts. Defaults to `5`. - Notes: +### `--lock-retry-max-attempts` -* 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. +```bash +atlantis server --lock-retry-max-attempts=3 +# or +ATLANTIS_LOCK_RETRY_MAX_ATTEMPTS=3 +``` -### `--log-level` +Maximum number of attempts to retry acquiring a lock when lock retry is enabled. Defaults to `3`. - ```bash - atlantis server --log-level="" - # or - ATLANTIS_LOG_LEVEL="" - ``` +### `--locking-db-type` - Log level. Defaults to `info`. +```bash +atlantis server --locking-db-type="" +# or +ATLANTIS_LOCKING_DB_TYPE="" +``` -### `--markdown-template-overrides-dir` +The locking database type to use for storing plan and apply locks. Defaults to `boltdb`. - ```bash - atlantis server --markdown-template-overrides-dir="path/to/templates/" - # or - ATLANTIS_MARKDOWN_TEMPLATE_OVERRIDES_DIR="path/to/templates/" - ``` +Notes: - This will be available in v0.21.0. +- 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. - 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. +### `--log-level` - Markdown templates which may have overrides can be found [here](https://github.com/runatlantis/atlantis/tree/main/server/events/templates) +```bash +atlantis server --log-level="" +# or +ATLANTIS_LOG_LEVEL="" +``` - Please be mindful that settings like `--enable-diff-markdown-format` depend on logic defined in the templates. It is - possible to diverge from expected behavior, if care is not taken when overriding default templates. +Log level. Defaults to `info`. - Defaults to the atlantis home directory `/home/atlantis/.markdown_templates/` in `/$HOME/.markdown_templates`. +### `--markdown-template-overrides-dir` -### `--max-comments-per-command` +```bash +atlantis server --markdown-template-overrides-dir="path/to/templates/" +# or +ATLANTIS_MARKDOWN_TEMPLATE_OVERRIDES_DIR="path/to/templates/" +``` - ```bash - atlantis server --max-comments-per-command=100 - # or - ATLANTIS_MAX_COMMENTS_PER_COMMAND=100 - ``` +This will be available in v0.21.0. - Limit the number of comments published after a command is executed, to prevent spamming your VCS and Atlantis to get throttled as a result. Defaults to `100`. Set this option to `0` to disable log truncation. Note that the truncation will happen on the top of the command output, to preserve the most important parts of the output, often displayed at the end. +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. -### `--parallel-apply` +Markdown templates which may have overrides can be found [markdown templates directory](https://github.com/runatlantis/atlantis/tree/main/server/events/templates) - ```bash - atlantis server --parallel-apply - # or - ATLANTIS_PARALLEL_APPLY=true - ``` +Please be mindful that settings like `--enable-diff-markdown-format` depend on logic defined in the templates. It is +possible to diverge from expected behavior, if care is not taken when overriding default templates. - 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. +Defaults to the atlantis home directory `/home/atlantis/.markdown_templates/` in `/$HOME/.markdown_templates`. -### `--parallel-plan` +### `--max-comments-per-command` - ```bash - atlantis server --parallel-plan - # or - ATLANTIS_PARALLEL_PLAN=true - ``` +```bash +atlantis server --max-comments-per-command=100 +# or +ATLANTIS_MAX_COMMENTS_PER_COMMAND=100 +``` - 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. +Limit the number of comments published after a command is executed, to prevent spamming your VCS and Atlantis to get throttled as a result. Defaults to `100`. Set this option to `0` to disable log truncation. Note that the truncation will happen on the top of the command output, to preserve the most important parts of the output, often displayed at the end. -### `--parallel-pool-size` +### `--parallel-apply` - ```bash - atlantis server --parallel-pool-size=100 - # or - ATLANTIS_PARALLEL_POOL_SIZE=100 - ``` +```bash +atlantis server --parallel-apply +# or +ATLANTIS_PARALLEL_APPLY=true +``` - Max size of the wait group that runs parallel plans and applies (if enabled). Defaults to `15` +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. -### `--port` +### `--parallel-plan` - ```bash - atlantis server --port=4141 - # or - ATLANTIS_PORT=4141 - ``` +```bash +atlantis server --parallel-plan +# or +ATLANTIS_PARALLEL_PLAN=true +``` - Port to bind to. Defaults to `4141`. +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. -### `--quiet-policy-checks` +### `--parallel-pool-size` - ```bash - atlantis server --quiet-policy-checks - # or - ATLANTIS_QUIET_POLICY_CHECKS=true - ``` +```bash +atlantis server --parallel-pool-size=100 +# or +ATLANTIS_PARALLEL_POOL_SIZE=100 +``` - Exclude policy check comments from pull requests unless there's an actual error from conftest. This also excludes warnings. Defaults to `false`. +Max size of the wait group that runs parallel plans and applies (if enabled). Defaults to `15` -### `--redis-db` +### `--port` - ```bash - atlantis server --redis-db=0 - # or - ATLANTIS_REDIS_DB=0 - ``` +```bash +atlantis server --port=4141 +# or +ATLANTIS_PORT=4141 +``` - The Redis Database to use when using a Locking DB type of `redis`. Defaults to `0`. +Port to bind to. Defaults to `4141`. -### `--redis-host` +### `--quiet-policy-checks` - ```bash - atlantis server --redis-host="localhost" - # or - ATLANTIS_REDIS_HOST="localhost" - ``` +```bash +atlantis server --quiet-policy-checks +# or +ATLANTIS_QUIET_POLICY_CHECKS=true +``` - The Redis Hostname for when using a Locking DB type of `redis`. +Exclude policy check comments from pull requests unless there's an actual error from conftest. This also excludes warnings. Defaults to `false`. -### `--redis-insecure-skip-verify` +### `--redis-db` - ```bash - atlantis server --redis-insecure-skip-verify=false - # or - ATLANTIS_REDIS_INSECURE_SKIP_VERIFY=false - ``` +```bash +atlantis server --redis-db=0 +# or +ATLANTIS_REDIS_DB=0 +``` - 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`. +The Redis Database to use when using a Locking DB type of `redis`. Defaults to `0`. - ::: warning SECURITY WARNING - If this is enabled, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. - ::: +### `--redis-host` -### `--redis-password` +```bash +atlantis server --redis-host="localhost" +# or +ATLANTIS_REDIS_HOST="localhost" +``` - ```bash - atlantis server --redis-password="password123" - # or (recommended) - ATLANTIS_REDIS_PASSWORD="password123" - ``` +The Redis Hostname for when using a Locking DB type of `redis`. - The Redis Password for when using a Locking DB type of `redis`. +### `--redis-insecure-skip-verify` -### `--redis-port` +```bash +atlantis server --redis-insecure-skip-verify=false +# or +ATLANTIS_REDIS_INSECURE_SKIP_VERIFY=false +``` - ```bash - atlantis server --redis-port=6379 - # or - ATLANTIS_REDIS_PORT=6379 - ``` +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`. - The Redis Port for when using a Locking DB type of `redis`. Defaults to `6379`. +::: warning SECURITY WARNING +If this is enabled, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. +::: -### `--redis-tls-enabled` +### `--redis-password` - ```bash - atlantis server --redis-tls-enabled=false - # or - ATLANTIS_REDIS_TLS_ENABLED=false - ``` +```bash +atlantis server --redis-password="password123" +# or (recommended) +ATLANTIS_REDIS_PASSWORD="password123" +``` - Enables a TLS connection, with min version of 1.2, to Redis when using a Locking DB type of `redis`. Defaults to `false`. +The Redis Password for when using a Locking DB type of `redis`. -### `--repo-allowlist` +### `--redis-port` - ```bash - # NOTE: Use single quotes to avoid shell expansion of *. - atlantis server --repo-allowlist='github.com/myorg/*' - # or - ATLANTIS_REPO_ALLOWLIST='github.com/myorg/*' - ``` +```bash +atlantis server --redis-port=6379 +# or +ATLANTIS_REDIS_PORT=6379 +``` - Atlantis requires you to specify an allowlist of repositories it will accept webhooks from. +The Redis Port for when using a Locking DB type of `redis`. Defaults to `6379`. - Notes: +### `--redis-tls-enabled` -* 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. +```bash +atlantis server --redis-tls-enabled=false +# or +ATLANTIS_REDIS_TLS_ENABLED=false +``` - Examples: +Enables a TLS connection, with min version of 1.2, to Redis when using a Locking DB type of `redis`. Defaults to `false`. -* 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-allowlist` -### `--repo-config` +```bash +# NOTE: Use single quotes to avoid shell expansion of *. +atlantis server --repo-allowlist='github.com/myorg/*' +# or +ATLANTIS_REPO_ALLOWLIST='github.com/myorg/*' +``` - ```bash - atlantis server --repo-config="path/to/repos.yaml" - # or - ATLANTIS_REPO_CONFIG="path/to/repos.yaml" - ``` +Atlantis requires you to specify an allowlist of repositories it will accept webhooks from. - Path to a YAML server-side repo config file. See [Server Side Repo Config](server-side-repo-config.md). +Notes: -### `--repo-config-json` +- 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. - ```bash - atlantis server --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}' - # or - ATLANTIS_REPO_CONFIG_JSON='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}' - ``` +Examples: - 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. +- 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='*'` - ::: tip - If specifying a [Workflow](custom-workflows.md#reference), [step](custom-workflows.md#step)'s - can be specified as follows: +### `--repo-config` - ```json - { - "repos": [], - "workflows": { +```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": [], + "workflows": { "custom": { - "plan": { - "steps": [ - "init", - { - "plan": { - "extra_args": ["extra", "args"] - } - }, - { - "run": "my custom command" - } - ] - } + "plan": { + "steps": [ + "init", + { + "plan": { + "extra_args": ["extra", "args"] + } + }, + { + "run": "my custom command" + } + ] + } } - } - } - ``` + } +} +``` - ::: +::: -### `--restrict-file-list` +### `--restrict-file-list` - ```bash - atlantis server --restrict-file-list - # or (recommended) - ATLANTIS_RESTRICT_FILE_LIST=true - ``` +```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 still be blocked if necessary. - Defaults to `false`. +`--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 still be blocked if necessary. +Defaults to `false`. -### `--silence-allowlist-errors` +### `--silence-allowlist-errors` - ```bash - atlantis server --silence-allowlist-errors - # or - ATLANTIS_SILENCE_ALLOWLIST_ERRORS=true - ``` +```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. +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. - Some users find this useful because they prefer to add the Atlantis webhook - at an organization level rather than on each repo. +Some users find this useful because they prefer to add the Atlantis webhook +at an organization level rather than on each repo. -### `--silence-fork-pr-errors` +### `--silence-fork-pr-errors` - ```bash - atlantis server --silence-fork-pr-errors - # or - ATLANTIS_SILENCE_FORK_PR_ERRORS=true - ``` +```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. +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` +### `--silence-no-projects` - ```bash - atlantis server --silence-no-projects - # or - ATLANTIS_SILENCE_NO_PROJECTS=true - ``` +```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`. - This also silences targeted commands (eg. `atlantis plan -d mydir` or `atlantis apply -p myproj`) so if the project is not in the repo config `atlantis.yaml`, these commands will not run or report back in a comment. +`--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`. +This also silences targeted commands (eg. `atlantis plan -d mydir` or `atlantis apply -p myproj`) so if the project is not in the repo config `atlantis.yaml`, these commands will not run or report back in a comment. - This is useful when running multiple Atlantis servers against a single repository so you can - delegate work to each Atlantis server. Also useful when used with pre_workflow_hooks to dynamically generate an `atlantis.yaml` file. +This is useful when running multiple Atlantis servers against a single repository so you can +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` +### `--silence-vcs-status-no-plans` - ```bash - atlantis server --silence-vcs-status-no-plans - # or - ATLANTIS_SILENCE_VCS_STATUS_NO_PLANS=true - ``` +```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-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` +### `--silence-vcs-status-no-projects` - ```bash - atlantis server --silence-vcs-status-no-projects - # or - ATLANTIS_SILENCE_VCS_STATUS_NO_PROJECTS=true - ``` +```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. +`--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` +### `--skip-clone-no-changes` - ```bash - atlantis server --skip-clone-no-changes - # or - ATLANTIS_SKIP_CLONE_NO_CHANGES=true - ``` +```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`. +`--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` +### `--slack-token` - ```bash - atlantis server --slack-token=token - # or (recommended) - ATLANTIS_SLACK_TOKEN='token' - ``` +```bash +atlantis server --slack-token=token +# or (recommended) +ATLANTIS_SLACK_TOKEN='token' +``` - API token for Slack notifications. See [Using Slack hooks](sending-notifications-via-webhooks.md#using-slack-hooks). +API token for Slack notifications. See [Using Slack hooks](sending-notifications-via-webhooks.md#using-slack-hooks). -### `--ssl-cert-file` +### `--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" - ``` +```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. +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` +### `--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" - ``` +```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`. +File containing x509 private key matching `--ssl-cert-file`. -### `--stats-namespace` +### `--stats-namespace` - ```bash - atlantis server --stats-namespace="myatlantis" - # or - ATLANTIS_STATS_NAMESPACE="myatlantis" - ``` +```bash +atlantis server --stats-namespace="myatlantis" +# or +ATLANTIS_STATS_NAMESPACE="myatlantis" +``` - Namespace for emitting stats/metrics. See [stats](stats.md) section. +Namespace for emitting stats/metrics. See [stats](stats.md) section. -### `--tf-distribution` +### `--tf-distribution` Deprecated for `--default-tf-distribution`. -### `--tf-download` +### `--tf-download` - ```bash - atlantis server --tf-download=false - # or - ATLANTIS_TF_DOWNLOAD=false - ``` +```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` +### `--tf-download-url` - ```bash - atlantis server --tf-download-url="https://releases.company.com" - # or - ATLANTIS_TF_DOWNLOAD_URL="https://releases.company.com" - ``` +```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. +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. - This has no impact if `--tf-download` is set to `false`. +This has no impact if `--tf-download` is set to `false`. - This setting is not yet supported when `--tf-distribution` is set to `opentofu`. +This setting is not yet supported when `--tf-distribution` is set to `opentofu`. -### `--tfe-hostname` +### `--tfe-hostname` - ```bash - atlantis server --tfe-hostname="my-terraform-enterprise.company.com" - # or - ATLANTIS_TFE_HOSTNAME="my-terraform-enterprise.company.com" - ``` +```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`. +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` +### `--tfe-local-execution-mode` - ```bash - atlantis server --tfe-local-execution-mode - # or - ATLANTIS_TFE_LOCAL_EXECUTION_MODE=true - ``` +```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. +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` +### `--tfe-token` - ```bash - atlantis server --tfe-token="xxx.atlasv1.yyy" - # or (recommended) - ATLANTIS_TFE_TOKEN='xxx.atlasv1.yyy' - ``` +```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. +A token for Terraform Cloud/Terraform Enterprise integration. See [Terraform Cloud](terraform-cloud.md) for more details. -### `--use-tf-plugin-cache` +### `--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 management of the PRs. -### `--var-file-allowlist` +### `--var-file-allowlist` - ```bash - atlantis server --var-file-allowlist='/path/to/tfvars/dir' - # or - ATLANTIS_VAR_FILE_ALLOWLIST='/path/to/tfvars/dir' - ``` +```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. +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` +### `--vcs-status-name` - ```bash - atlantis server --vcs-status-name="atlantis-dev" - # or - ATLANTIS_VCS_STATUS_NAME="atlantis-dev" - ``` +```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`. +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. +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` +### `--web-basic-auth` - ```bash - atlantis server --web-basic-auth - # or - ATLANTIS_WEB_BASIC_AUTH=true - ``` +```bash +atlantis server --web-basic-auth +# or +ATLANTIS_WEB_BASIC_AUTH=true +``` - Enable Basic Authentication on the Atlantis web service. +Enable Basic Authentication on the Atlantis web service. -### `--web-password` +### `--web-password` - ```bash - atlantis server --web-password="atlantis" - # or - ATLANTIS_WEB_PASSWORD="atlantis" - ``` +```bash +atlantis server --web-password="atlantis" +# or +ATLANTIS_WEB_PASSWORD="atlantis" +``` - Password used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. +Password used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. -### `--web-username` +### `--web-username` - ```bash - atlantis server --web-username="atlantis" - # or - ATLANTIS_WEB_USERNAME="atlantis" - ``` +```bash +atlantis server --web-username="atlantis" +# or +ATLANTIS_WEB_USERNAME="atlantis" +``` - Username used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. +Username used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. -### `--webhook-http-headers` +### `--webhook-http-headers` - ```bash - atlantis server --webhook-http-headers='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}' - # or - ATLANTIS_WEBHOOK_HTTP_HEADERS='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}' - ``` +```bash +atlantis server --webhook-http-headers='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}' +# or +ATLANTIS_WEBHOOK_HTTP_HEADERS='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}' +``` - Additional headers added to each HTTP POST payload when using [http webhooks](sending-notifications-via-webhooks.md#using-http-webhooks) - provided as a JSON string. The map key is the header name and the value is the header value - (string) or values (array of string). +Additional headers added to each HTTP POST payload when using [http webhooks](sending-notifications-via-webhooks.md#using-http-webhooks) +provided as a JSON string. The map key is the header name and the value is the header value +(string) or values (array of string). -### `--websocket-check-origin` +### `--websocket-check-origin` - ```bash - atlantis server --websocket-check-origin - # or - ATLANTIS_WEBSOCKET_CHECK_ORIGIN=true - ``` +```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 +Only allow websockets connection when they originate from the running Atlantis web server -### `--write-git-creds` +### `--write-git-creds` - ```bash - atlantis server --write-git-creds - # or - ATLANTIS_WRITE_GIT_CREDS=true - ``` +```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. +Write out a .git-credentials file with the provider user and token to allow +cloning private modules over HTTPS or SSH. See [Git Credential Store documentation](https://git-scm.com/docs/git-credential-store) for more information. - Follow the `git::ssh` syntax to avoid using a custom `.gitconfig` with an `insteadOf`. - - ```hcl - module "private_submodule" { - source = "git::ssh://git@github.com////modules/?ref=v1.2.3" - - # ... - } - ``` - - ::: warning SECURITY WARNING - This does write secrets to disk and should only be enabled in a secure environment. - ::: +Follow the `git::ssh`