diff --git a/runatlantis.io/.vitepress/config.ts b/runatlantis.io/.vitepress/config.ts index d967212730..a631027807 100644 --- a/runatlantis.io/.vitepress/config.ts +++ b/runatlantis.io/.vitepress/config.ts @@ -1,6 +1,6 @@ -import { defineConfig } from 'vitepress'; -import * as navbars from "./navbars"; -import * as sidebars from "./sidebars"; +import { defineConfig } from 'vitepress' +import * as navbars from "./navbars" +import * as sidebars from "./sidebars" // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -23,6 +23,10 @@ export default defineConfig({ editLink: { pattern: 'https://github.com/runatlantis/atlantis/edit/main/runatlantis.io/:path' }, + // headline "depth" the right nav will show for its TOC + // + // https://vitepress.dev/reference/frontmatter-config#outline + outline: [2, 3], search: { provider: 'algolia', options: { @@ -45,9 +49,9 @@ export default defineConfig({ } }, socialLinks: [ - { icon: "slack", link: "https://join.slack.com/t/atlantis-community/shared_invite/zt-9xlxtxtc-CUSKB1ATt_sQy6um~LDPNw" }, - { icon: "twitter", link: "https://twitter.com/runatlantis" }, - { icon: "github", link: "https://github.com/runatlantis/atlantis" }, + { icon: "slack", link: "https://join.slack.com/t/atlantis-community/shared_invite/zt-9xlxtxtc-CUSKB1ATt_sQy6um~LDPNw" }, + { icon: "twitter", link: "https://twitter.com/runatlantis" }, + { icon: "github", link: "https://github.com/runatlantis/atlantis" }, ], }, head: [ diff --git a/runatlantis.io/docs/access-credentials.md b/runatlantis.io/docs/access-credentials.md index 1e46c9de24..d2673a4c34 100644 --- a/runatlantis.io/docs/access-credentials.md +++ b/runatlantis.io/docs/access-credentials.md @@ -1,10 +1,11 @@ # Git Host Access Credentials + This page describes how to create credentials for your Git host (GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps) that Atlantis will use to make API calls. -[[toc]] ## Create an Atlantis user (optional) + We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user. This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes @@ -14,8 +15,10 @@ will come from that user so it might be confusing if its coming from a personal

An example comment coming from the @atlantisbot user

## Generating an Access Token + Once you've created a new user (or decided to use an existing one), you need to generate an access token. Read on for the instructions for your specific Git host: + * [GitHub](#github-user) * [GitHub app](#github-app) * [GitLab](#gitlab) @@ -25,9 +28,10 @@ generate an access token. Read on for the instructions for your specific Git hos * [Azure DevOps](#azure-devops) ### GitHub user + - Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token) -- Create the token with **repo** scope -- Record the access token +* Create the token with **repo** scope +* Record the access token ::: warning Your Atlantis user must also have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses: ![Atlantis status](./images/status.png) @@ -36,16 +40,16 @@ Your Atlantis user must also have "Write permissions" (for repos in an organizat ### GitHub app #### Create the GitHub App Using Atlantis + ::: warning Available in Atlantis versions **newer** than 0.13.0. ::: - -- Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command. -- Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis -- A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link. -- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` -- Restart Atlantis with new flags: `atlantis server --gh-app-id --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`. +* Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command. +* Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis +* A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link. +* Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` +* Restart Atlantis with new flags: `atlantis server --gh-app-id --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`. NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file). @@ -59,11 +63,11 @@ GitHub App handles the webhook calls by itself, hence there is no need to create #### Manually Creating the GitHub app -- Create the GitHub app as an Administrator - - Ensure the app is registered / installed with the organization / user - - See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) -- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` -- Start Atlantis with the following flags: `atlantis server --gh-app-id --gh-installation-id --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`. +* Create the GitHub app as an Administrator + * Ensure the app is registered / installed with the organization / user + * See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) +* Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem` +* Start Atlantis with the following flags: `atlantis server --gh-app-id --gh-installation-id --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`. NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file). @@ -93,56 +97,62 @@ Since v0.19.7, a new permission for `Administration` has been added. If you have Since v0.22.3, a new permission for `Members` has been added, which is required for features that apply permissions to an organizations team members rather than individual users. Like the `Administration` permission above, updating Atlantis will not automatically add this permission, so if you wish to use features that rely on checking team membership you will need to add this manually. ::: -| Type | Access | -| --------------- | ------------------- | -| Administration | Read-only | -| Checks | Read and write | -| Commit statuses | Read and write | -| Contents | Read and write | -| Issues | Read and write | -| Metadata | Read-only (default) | -| Pull requests | Read and write | -| Webhooks | Read and write | -| Members | Read-only | +| Type | Access | +| --------------- | ------------------- | +| Administration | Read-only | +| Checks | Read and write | +| Commit statuses | Read and write | +| Contents | Read and write | +| Issues | Read and write | +| Metadata | Read-only (default) | +| Pull requests | Read and write | +| Webhooks | Read and write | +| Members | Read-only | ### GitLab + - Follow: [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token) -- Create a token with **api** scope -- Record the access token +* Create a token with **api** scope +* Record the access token ### Gitea + - Go to "Profile and Settings" > "Settings" in Gitea (top-right) -- Go to "Applications" under "User Settings" in Gitea -- Create a token under the "Manage Access Tokens" with the following permissions: - - issue: Read and Write - - repository: Read and Write - - user: Read -- Record the access token +* Go to "Applications" under "User Settings" in Gitea +* Create a token under the "Manage Access Tokens" with the following permissions: + * issue: Read and Write + * repository: Read and Write + * user: Read +* Record the access token ### Bitbucket Cloud (bitbucket.org) + - Create an App Password by following [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/) -- Label the password "atlantis" -- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them -- Record the access token +* Label the password "atlantis" +* Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them +* Record the access token ### Bitbucket Server (aka Stash) + - Click on your avatar in the top right and select **Manage account** -- Click **Personal access tokens** in the sidebar -- Click **Create a token** -- Name the token **atlantis** -- Give the token **Read** Project permissions and **Write** Pull request permissions -- Click **Create** and record the access token +* Click **Personal access tokens** in the sidebar +* Click **Create a token** +* Name the token **atlantis** +* Give the token **Read** Project permissions and **Write** Pull request permissions +* Click **Create** and record the access token NOTE: Atlantis will send the token as a [Bearer Auth to the Bitbucket API](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html#HTTPaccesstokens-UsingHTTPaccesstokens) instead of using Basic Auth. ### Azure DevOps + - Create a Personal access token by following [Azure DevOps: Use personal access tokens to authenticate](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops) -- Label the password "atlantis" -- The minimum scopes required for this token are: - - Code (Read & Write) - - Code (Status) - - Member Entitlement Management (Read) -- Record the access token +* Label the password "atlantis" +* The minimum scopes required for this token are: + * Code (Read & Write) + * Code (Status) + * Member Entitlement Management (Read) +* Record the access token ## Next Steps + Once you've got your user and access token, you're ready to create a webhook secret. See [Creating a Webhook Secret](webhook-secrets.md). diff --git a/runatlantis.io/docs/command-requirements.md b/runatlantis.io/docs/command-requirements.md index 046542f786..70313d69de 100644 --- a/runatlantis.io/docs/command-requirements.md +++ b/runatlantis.io/docs/command-requirements.md @@ -1,7 +1,7 @@ # Command Requirements -[[toc]] ## Intro + Atlantis requires certain conditions be satisfied **before** `atlantis apply` and `atlantis import` commands can be run: @@ -10,31 +10,41 @@ commands can be run: * [UnDiverged](#undiverged) - requires pull requests to be ahead of the base branch ## What Happens If The Requirement Is Not Met? + If the requirement is not met, users will see an error if they try to run `atlantis apply`: ![Mergeable Apply Requirement](./images/apply-requirement.png) ## Supported Requirements + ### Approved + The `approved` requirement will prevent applies unless the pull request is approved by at least one person other than the author. #### Usage + The `approved` requirement by: + 1. Creating a `repos.yaml` file with the `apply_requirements` key: + ```yaml repos: - id: /.*/ apply_requirements: [approved] ``` + 1. Or by allowing an `atlantis.yaml` file to specify the `apply_requirements` key in the `repos.yaml` config: - #### repos.yaml + +#### repos.yaml + ```yaml repos: - id: /.*/ allowed_overrides: [apply_requirements] ``` - #### atlantis.yaml +#### atlantis.yaml + ```yaml version: 3 projects: @@ -43,7 +53,9 @@ The `approved` requirement by: ``` #### Meaning + Each VCS provider has different rules around who can approve: + * **GitHub** – **Any user with read permissions** to the repo can approve a pull request * **GitLab** – The user who can approve can be set in the [repo settings](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) * **Bitbucket Cloud (bitbucket.org)** – A user can approve their own pull request but @@ -57,11 +69,15 @@ To require **certain people** to approve the pull request, look at the ::: ### Mergeable + The `mergeable` requirement will prevent applies unless a pull request is able to be merged. #### Usage + Set the `mergeable` requirement by: + 1. Creating a `repos.yaml` file with the `apply_requirements` key: + ```yaml repos: - id: /.*/ @@ -69,14 +85,17 @@ Set the `mergeable` requirement by: ``` 1. Or by allowing an `atlantis.yaml` file to specify `plan_requirements`, `apply_requirements` and `import_requirements` keys in the `repos.yaml` config: - #### repos.yaml + +#### repos.yaml + ```yaml repos: - id: /.*/ allowed_overrides: [plan_requirements, apply_requirements, import_requirements] ``` - #### atlantis.yaml +#### atlantis.yaml + ```yaml version: 3 projects: @@ -87,6 +106,7 @@ Set the `mergeable` requirement by: ``` #### Meaning + Each VCS provider has a different concept of "mergeability": ::: warning @@ -96,10 +116,12 @@ See also the `branch` keyword in [Server Side Repo Config](server-side-repo-conf ::: #### GitHub + In GitHub, if you're not using [Protected Branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) then all pull requests are mergeable unless there is a conflict. If you set up Protected Branches then you can enforce: + * Requiring certain status checks to be passing * Requiring certain people to have reviewed and approved the pull request * Requiring `CODEOWNERS` to have reviewed and approved the pull request @@ -119,6 +141,7 @@ If you set `atlantis/apply` to the mergeable requirement, use the `--gh-allow-me ::: #### GitLab + For GitLab, a merge request will be merged if there are no conflicts, no unresolved discussions if it is a project requirement and if all necessary approvers have approved the pull request. For pipelines, if the project requires that pipelines must succeed, all builds except the apply command status will be checked. @@ -126,6 +149,7 @@ For pipelines, if the project requires that pipelines must succeed, all builds e For Jobs with allow_failure setting set to true, will be ignored. If the pipeline has been skipped and the project allows merging, it will be marked as mergeable. #### Bitbucket.org (Bitbucket Cloud) and Bitbucket Server (Stash) + For Bitbucket, we just check if there is a conflict that is preventing a merge. We don't check anything else because Bitbucket's API doesn't support it. @@ -133,9 +157,11 @@ If you need a specific check, please [open an issue](https://github.com/runatlantis/atlantis/issues/new). #### Azure DevOps + In Azure DevOps, all pull requests are mergeable unless there is a conflict. You can set a pull request to "Complete" right away, or set "Auto-Complete", which will merge after all branch policies are met. See [Review code with pull requests](https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-requests?view=azure-devops). [Branch policies](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops) can: + * Require a minimum number of reviewers * Allow users to approve their own changes * Allow completion even if some reviewers vote "Waiting" or "Reject" @@ -147,12 +173,16 @@ At this time, the Azure DevOps client only supports merging using the default 'n ::: ### UnDiverged + Prevent applies if there are any changes on the base branch since the most recent plan. Applies to `merge` checkout strategy only which you need to set via `--checkout-strategy` flag. #### Usage + You can set the `undiverged` requirement by: + 1. Creating a `repos.yaml` file with `plan_requirements`, `apply_requirements` and `import_requirements` keys: + ```yaml repos: - id: /.*/ @@ -160,15 +190,19 @@ You can set the `undiverged` requirement by: apply_requirements: [undiverged] import_requirements: [undiverged] ``` + 1. Or by allowing an `atlantis.yaml` file to specify the `plan_requirements`, `apply_requirements` and `import_requirements` keys in your `repos.yaml` config: - #### repos.yaml + +#### repos.yaml + ```yaml repos: - id: /.*/ allowed_overrides: [plan_requirements, apply_requirements, import_requirements] ``` - #### atlantis.yaml +#### atlantis.yaml + ```yaml version: 3 projects: @@ -177,7 +211,9 @@ You can set the `undiverged` requirement by: apply_requirements: [undiverged] import_requirements: [undiverged] ``` + #### Meaning + The `merge` checkout strategy creates a temporary merge commit and runs the `plan` on the Atlantis local version of the PR source and destination branch. The local destination branch can become out of date since changes to the destination branch are not fetched if there are no changes to the source branch. `undiverged` enforces that Atlantis local version of main is up to date @@ -185,16 +221,21 @@ with remote so that the state of the source during the `apply` is identical to t time. ## Setting Command Requirements + As mentioned above, you can set command requirements via flags, in `repos.yaml`, or in `atlantis.yaml` if `repos.yaml` allows the override. ### Flags Override + Flags **override** any `repos.yaml` or `atlantis.yaml` settings so they are equivalent to always having that apply requirement set. ### Project-Specific Settings + If you only want some projects/repos to have apply requirements, then you must + 1. Specifying which repos have which requirements via the `repos.yaml` file. + ```yaml repos: - id: /.*/ @@ -221,7 +262,9 @@ If you only want some projects/repos to have apply requirements, then you must config. For example if I have two directories, `staging` and `production`, I might use: - #### repos.yaml + +#### repos.yaml + ```yaml repos: - id: /.*/ @@ -229,7 +272,8 @@ If you only want some projects/repos to have apply requirements, then you must # Allow any repo to specify apply_requirements in atlantis.yaml ``` - #### atlantis.yaml +#### atlantis.yaml + ```yaml version: 3 projects: @@ -248,13 +292,16 @@ If you only want some projects/repos to have apply requirements, then you must ``` ### Multiple Requirements + You can set any or all of `approved`, `mergeable`, and `undiverged` requirements. ## Who Can Apply? + Once the apply requirement is satisfied, **anyone** that can comment on the pull request can run the actual `atlantis apply` command. ## Next Steps + * For more information on GitHub pull request reviews and approvals see: [GitHub: About pull request reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) * For more information on GitLab merge request reviews and approvals (only supported on GitLab Enterprise) see: [GitLab: Merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/). * For more information on Bitbucket pull request reviews and approvals see: [BitBucket: Use pull requests for code review](https://confluence.atlassian.com/bitbucket/pull-requests-and-code-review-223220593.html) diff --git a/runatlantis.io/docs/configuring-webhooks.md b/runatlantis.io/docs/configuring-webhooks.md index 82a6e1d3c3..7545e127b1 100644 --- a/runatlantis.io/docs/configuring-webhooks.md +++ b/runatlantis.io/docs/configuring-webhooks.md @@ -1,16 +1,18 @@ # Configuring Webhooks + Atlantis needs to receive Webhooks from your Git host so that it can respond to pull request events. :::tip Prerequisites + * You have created an [access credential](access-credentials.md) * You have created a [webhook secret](webhook-secrets.md) * You have [deployed](deployment.md) Atlantis and have a url for it ::: See the instructions for your specific provider below. -[[toc]] ## GitHub/GitHub Enterprise + You can install your webhook at the [organization](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts) level, or for each individual repository. ::: tip NOTE @@ -22,121 +24,127 @@ When authenticating as a GitHub App, Webhooks are automatically created and need If you're installing on the organization, navigate to your organization's page and click **Settings**. If installing on a single repository, navigate to the repository home page and click **Settings**. -- Select **Webhooks** or **Hooks** in the sidebar -- Click **Add webhook** -- set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** -- double-check you added `/events` to the end of your URL. -- set **Content type** to `application/json` -- set **Secret** to the Webhook Secret you generated previously - - **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. -- select **Let me select individual events** -- check the boxes - - **Pull request reviews** - - **Pushes** - - **Issue comments** - - **Pull requests** -- leave **Active** checked -- click **Add webhook** -- See [Next Steps](#next-steps) +* Select **Webhooks** or **Hooks** in the sidebar +* Click **Add webhook** +* set **Payload URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** +* double-check you added `/events` to the end of your URL. +* set **Content type** to `application/json` +* set **Secret** to the Webhook Secret you generated previously + * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. +* select **Let me select individual events** +* check the boxes + * **Pull request reviews** + * **Pushes** + * **Issue comments** + * **Pull requests** +* leave **Active** checked +* click **Add webhook** +* See [Next Steps](#next-steps) ## GitLab + If you're using GitLab, navigate to your project's home page in GitLab -- Click **Settings > Webhooks** in the sidebar -- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** -- double-check you added `/events` to the end of your URL. -- set **Secret Token** to the Webhook Secret you generated previously - - **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. -- check the boxes - - **Push events** - - **Comments** - - **Merge Request events** -- leave **Enable SSL verification** checked -- click **Add webhook** -- See [Next Steps](#next-steps) +* Click **Settings > Webhooks** in the sidebar +* set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** +* double-check you added `/events` to the end of your URL. +* set **Secret Token** to the Webhook Secret you generated previously + * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. +* check the boxes + * **Push events** + * **Comments** + * **Merge Request events** +* leave **Enable SSL verification** checked +* click **Add webhook** +* See [Next Steps](#next-steps) ## Gitea + If you're using Gitea, navigate to your project's home page in Gitea -- Click **Settings > Webhooks** in the top- and then sidebar -- Click **Add webhook > Gitea** (Gitea webhooks are service specific, but this works) -- set **Target URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** -- double-check you added `/events` to the end of your URL. -- set **Secret** to the Webhook Secret you generated previously - - **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. -- Select **Custom Events...** -- Check the boxes - - **Repository events > Push** - - **Issue events > Issue Comment** - - **Pull Request events > Pull Request** - - **Pull Request events > Pull Request Comment** - - **Pull Request events > Pull Request Reviewed** - - **Pull Request events > Pull Request Synchronized** -- Leave **Active** checked -- Click **Add Webhook** -- See [Next Steps](#next-steps) +* Click **Settings > Webhooks** in the top- and then sidebar +* Click **Add webhook > Gitea** (Gitea webhooks are service specific, but this works) +* set **Target URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** +* double-check you added `/events` to the end of your URL. +* set **Secret** to the Webhook Secret you generated previously + * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. +* Select **Custom Events...** +* Check the boxes + * **Repository events > Push** + * **Issue events > Issue Comment** + * **Pull Request events > Pull Request** + * **Pull Request events > Pull Request Comment** + * **Pull Request events > Pull Request Reviewed** + * **Pull Request events > Pull Request Synchronized** +* Leave **Active** checked +* Click **Add Webhook** +* See [Next Steps](#next-steps) ## Bitbucket Cloud (bitbucket.org) + - Go to your repo's home page -- Click **Settings** in the sidebar -- Click **Webhooks** under the **WORKFLOW** section -- Click **Add webhook** -- Enter "Atlantis" for **Title** -- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** -- double-check you added `/events` to the end of your URL. -- Keep **Status** as Active -- Don't check **Skip certificate validation** because NGROK has a valid cert. -- Select **Choose from a full list of triggers** -- Under **Repository** **un**check everything -- Under **Issues** leave everything **un**checked -- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created -- Click **Save** +* Click **Settings** in the sidebar +* Click **Webhooks** under the **WORKFLOW** section +* Click **Add webhook** +* Enter "Atlantis" for **Title** +* set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** +* double-check you added `/events` to the end of your URL. +* Keep **Status** as Active +* Don't check **Skip certificate validation** because NGROK has a valid cert. +* Select **Choose from a full list of triggers** +* Under **Repository** **un**check everything +* Under **Issues** leave everything **un**checked +* Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created +* Click **Save** Bitbucket Webhook -- See [Next Steps](#next-steps) +* See [Next Steps](#next-steps) ## Bitbucket Server (aka Stash) + - Go to your repo's home page -- Click **Settings** in the sidebar -- Click **Webhooks** under the **WORKFLOW** section -- Click **Create webhook** -- Enter "Atlantis" for **Name** -- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** -- Double-check you added `/events` to the end of your URL. -- Set **Secret** to the Webhook Secret you generated previously - - **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. -- Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added -- Click **Save**Bitbucket Webhook -- See [Next Steps](#next-steps) +* Click **Settings** in the sidebar +* Click **Webhooks** under the **WORKFLOW** section +* Click **Create webhook** +* Enter "Atlantis" for **Name** +* set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`** +* Double-check you added `/events` to the end of your URL. +* Set **Secret** to the Webhook Secret you generated previously + * **NOTE** If you're adding a webhook to multiple repositories, each repository will need to use the **same** secret. +* Under **Pull Request**, select: Opened, Source branch updated, Merged, Declined, Deleted and Comment added +* Click **Save**Bitbucket Webhook +* See [Next Steps](#next-steps) ## Azure DevOps + Webhooks are installed at the [team project](https://docs.microsoft.com/en-us/azure/devops/organizations/projects/about-projects?view=azure-devops) level, but may be restricted to only fire based on events pertaining to [specific repos](https://docs.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops) within the team project. -- Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName` -- Select **Project settings** in the lower-left corner -- Select **Service hooks** - - If you see the message "You do not have sufficient permissions to view or configure subscriptions." you need to ensure your user is a member of either the organization's "Project Collection Administrators" group or the project's "Project Administrators" group. - - To add your user to the Project Collection Build Administrators group, navigate to the organization level, click **Organization Settings** and then click **Permissions**. You should be at `https://dev.azure.com//_settings/groups`. Now click on the **\/Project Collection Administrators** group and add your user as a member. - - To add your user to the Project Administrators group, navigate to the project level, click **Project Settings** and then click **Permissions**. You should be at `https://dev.azure.com///_settings/permissions`. Now click on the **\/Project Administrators** group and add your user as a member. -- Click **Create subscription** or the green plus icon to add a new webhook -- Scroll to the bottom of the list and select **Web Hooks** -- Click **Next** -- Under "Trigger on this type of event", select **Pull request created** - - Optionally, select a repository under **Filters** to restrict the scope of this webhook subscription to a specific repository -- Click **Next** -- Set **URL** to `http://$URL/events` where `$URL` is where Atlantis is hosted. Note that SSL, or `https://$URL/events`, is required if you set a Basic username and password for the webhook). **Be sure to add `/events`** -- It is strongly recommended to set a Basic Username and Password for all webhooks -- Leave all three drop-down menus for `...to send` set to **All** -- Resource version should be set to **1.0** for `Pull request created` and `Pull request updated` event types and **2.0** for `Pull request commented on` -- **NOTE** If you're adding a webhook to multiple team projects or repositories (using filters), each repository will need to use the **same** basic username and password. -- Click **Finish** +* Navigate anywhere within a team project, ie: `https://dev.azure.com/orgName/projectName/_git/repoName` +* Select **Project settings** in the lower-left corner +* Select **Service hooks** + * If you see the message "You do not have sufficient permissions to view or configure subscriptions." you need to ensure your user is a member of either the organization's "Project Collection Administrators" group or the project's "Project Administrators" group. + * To add your user to the Project Collection Build Administrators group, navigate to the organization level, click **Organization Settings** and then click **Permissions**. You should be at `https://dev.azure.com//_settings/groups`. Now click on the **\/Project Collection Administrators** group and add your user as a member. + * To add your user to the Project Administrators group, navigate to the project level, click **Project Settings** and then click **Permissions**. You should be at `https://dev.azure.com///_settings/permissions`. Now click on the **\/Project Administrators** group and add your user as a member. +* Click **Create subscription** or the green plus icon to add a new webhook +* Scroll to the bottom of the list and select **Web Hooks** +* Click **Next** +* Under "Trigger on this type of event", select **Pull request created** + * Optionally, select a repository under **Filters** to restrict the scope of this webhook subscription to a specific repository +* Click **Next** +* Set **URL** to `http://$URL/events` where `$URL` is where Atlantis is hosted. Note that SSL, or `https://$URL/events`, is required if you set a Basic username and password for the webhook). **Be sure to add `/events`** +* It is strongly recommended to set a Basic Username and Password for all webhooks +* Leave all three drop-down menus for `...to send` set to **All** +* Resource version should be set to **1.0** for `Pull request created` and `Pull request updated` event types and **2.0** for `Pull request commented on` +* **NOTE** If you're adding a webhook to multiple team projects or repositories (using filters), each repository will need to use the **same** basic username and password. +* Click **Finish** Repeat the process above until you have webhook subscriptions for the following event types that will trigger on all repositories Atlantis will manage: -- Pull request created (you just added this one) -- Pull request updated -- Pull request commented on +* Pull request created (you just added this one) +* Pull request updated +* Pull request commented on -- See [Next Steps](#next-steps) +* See [Next Steps](#next-steps) ## Next Steps + * To verify that Atlantis is receiving your webhooks, create a test pull request to your repo. * You should see the request show up in the Atlantis logs at an `INFO` level. * You'll now need to configure Atlantis to add your [Provider Credentials](provider-credentials.md) diff --git a/runatlantis.io/docs/custom-workflows.md b/runatlantis.io/docs/custom-workflows.md index 42a3db3539..4b5ad4b9d1 100644 --- a/runatlantis.io/docs/custom-workflows.md +++ b/runatlantis.io/docs/custom-workflows.md @@ -3,22 +3,24 @@ Custom workflows can be defined to override the default commands that Atlantis runs. -[[toc]] - ## Usage + Custom workflows can be specified in the Server-Side Repo Config or in the Repo-Level `atlantis.yaml` files. **Notes** + * If you want to allow repos to select their own workflows, they must have the `allowed_overrides: [workflow]` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-choose-a-server-side-workflow) for more details. * If in addition you also want to allow repos to define their own workflows, they must have the `allow_custom_workflows: true` setting. See [server-side repo config use cases](server-side-repo-config.md#allow-repos-to-define-their-own-workflows) for more details. - ## Use Cases + ### .tfvars files + Given the structure: + ``` . └── project1 @@ -29,6 +31,7 @@ Given the structure: If you wanted Atlantis to automatically run plan with `-var-file staging.tfvars` and `-var-file production.tfvars` you could define two workflows: + ```yaml # repos.yaml or atlantis.yaml workflows: @@ -40,7 +43,7 @@ workflows: extra_args: ["-var-file", "staging.tfvars"] # NOTE: no need to define the apply stage because it will default # to the normal apply stage. - + production: plan: steps: @@ -62,7 +65,9 @@ workflows: - state_rm: extra_args: ["-lock=false"] ``` + Then in your repo-level `atlantis.yaml` file, you would reference the workflows: + ```yaml # atlantis.yaml version: 3 @@ -80,19 +85,26 @@ workflows: # If you didn't define the workflows in your server-side repos.yaml config, # you would define them here instead. ``` + When you want to apply the plans, you can comment + ``` atlantis apply -p project1-staging ``` + and + ``` atlantis apply -p project1-production ``` + Where `-p` refers to the project name. ### Adding extra arguments to Terraform commands + If you need to append flags to `terraform plan` or `apply` temporarily, you can append flags on a comment following `--`, for example commenting: + ``` atlantis plan -- -lock=false ``` @@ -130,6 +142,7 @@ workflows: ``` ### Custom init/plan/apply Commands + If you want to customize `terraform init`, `plan` or `apply` in ways that aren't supported by `extra_args`, you can completely override those commands. @@ -147,11 +160,11 @@ workflows: - run: command: terraform init -input=false output: hide - + # If you're using workspaces you need to select the workspace using the # $WORKSPACE environment variable. - run: terraform workspace select $WORKSPACE - + # You MUST output the plan using -out $PLANFILE because Atlantis expects # plans to be in a specific location. - run: terraform plan -input=false -refresh -out $PLANFILE @@ -162,14 +175,15 @@ workflows: ``` ### CDKTF + Here are the requirements to enable [CDKTF](https://developer.hashicorp.com/terraform/cdktf) -- A custom image with `CDKTF` installed -- Add `**/cdk.tf.json` to the list of Atlantis autoplan files. -- Set the `atlantis-include-git-untracked-files` flag so that the Terraform files dynamically generated +* A custom image with `CDKTF` installed +* Add `**/cdk.tf.json` to the list of Atlantis autoplan files. +* Set the `atlantis-include-git-untracked-files` flag so that the Terraform files dynamically generated by CDKTF will be add to the Atlantis modified file list. -- Use `pre_workflow_hooks` to run `cdktf synth` -- Optional: There isn't a requirement to use a repo `atlantis.yaml` but one can be leveraged if needed. +* Use `pre_workflow_hooks` to run `cdktf synth` +* Optional: There isn't a requirement to use a repo `atlantis.yaml` but one can be leveraged if needed. #### Custom Image @@ -192,6 +206,7 @@ ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true OR `atlantis server --config config.yaml` + ```yaml # config.yaml autoplan-file-list: "**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json" @@ -203,6 +218,7 @@ include-git-untracked-files: true Use `pre_workflow_hooks` `atlantis server --repo-config="repos.yaml"` + ```yaml # repos.yaml repos: @@ -234,7 +250,7 @@ $ tree --gitignore 1. Container orchestrator (k8s/fargate/ecs/etc) uses the custom docker image of atlantis with `cdktf` installed with the `--autoplan-file-list` to trigger on `cdk.tf.json` files and `--include-git-untracked-files` set to include the -CDKTF dynamically generated Terraform files in the Atlantis plan. +CDKTF dynamically generated Terraform files in the Atlantis plan. 1. PR branch is pushed up containing `cdktf` code changes. 1. Atlantis checks out the branch in the repo. 1. Atlantis runs the `npm i && cdktf get && cdktf synth` command in the repo root as a step in `pre_workflow_hooks`, @@ -243,6 +259,7 @@ generating the `cdk.tf.json` Terraform files. 1. Atlantis then runs `terraform` workflows in the respective directories as usual. ### Terragrunt + Atlantis supports running custom commands in place of the default Atlantis commands. We can use this functionality to enable [Terragrunt](https://github.com/gruntwork-io/terragrunt). @@ -250,6 +267,7 @@ commands. We can use this functionality to enable You can either use your repo's `atlantis.yaml` file or the Atlantis server's `repos.yaml` file. Given a directory structure: + ``` . └── live @@ -315,6 +333,7 @@ workflows: ``` If using the repo's `atlantis.yaml` file you would use the following config: + ```yaml version: 3 projects: @@ -350,7 +369,6 @@ workflows: **NOTE:** If using the repo's `atlantis.yaml` file, you will need to specify each directory that is a Terragrunt project. - ::: warning Atlantis will need to have the `terragrunt` binary in its PATH. If you're using Docker you can build your own image, see [Customization](deployment.md#customization). @@ -361,6 +379,7 @@ If you don't want to create/manage the repo's `atlantis.yaml` file yourself, you The `terragrunt-atlantis-config` tool is a community project and not maintained by the Atlantis team. ### Running custom commands + Atlantis supports running completely custom commands. In this example, we want to run a script after every `apply`: @@ -375,17 +394,19 @@ workflows: ``` ::: tip Notes + * We don't need to write a `plan` key under `myworkflow`. If `plan` isn't set, Atlantis will use the default plan workflow which is what we want in this case. * A custom command will only terminate if all output file descriptors are closed. Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during the terraform run) when its output is redirected to a different location. For example, Atlantis -will execute a custom script containing the following code to create a SSH tunnel correctly: +will execute a custom script containing the following code to create a SSH tunnel correctly: `ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without the redirect, the script would block the Atlantis workflow. ::: ### Custom Backend Config + If you need to specify the `-backend-config` flag to `terraform init` you'll need to use a custom workflow. In this example, we're using custom backend files to configure two remote states, one for each environment. We're then using `.tfvars` files to load different variables for each environment. @@ -410,12 +431,14 @@ workflows: - plan: extra_args: [-var-file=production.tfvars] ``` + ::: warning NOTE We have to use a custom `run` step to `rm -rf .terraform` because otherwise Terraform will complain in-between commands since the backend config has changed. ::: You would then reference the workflows in your repo-level `atlantis.yaml`: + ```yaml version: 3 projects: @@ -428,7 +451,9 @@ projects: ``` ## Reference + ### Workflow + ```yaml plan: apply: @@ -444,6 +469,7 @@ state_rm: | state_rm | [Stage](#stage) | `steps: [init, state_rm]` | no | How to run state rm for this project. | ### Stage + ```yaml steps: - run: custom-command @@ -457,8 +483,11 @@ steps: | steps | array[[Step](#step)] | `[]` | no | List of steps for this stage. If the steps key is empty, no steps will be run for this stage. | ### Step + #### Built-In Commands + Steps can be a single string for a built-in command. + ```yaml - init - plan @@ -466,12 +495,15 @@ Steps can be a single string for a built-in command. - import - state_rm ``` + | Key | Type | Default | Required | Description | |---------------------------------|--------|---------|----------|------------------------------------------------------------------------------------------------------------------------------| | init/plan/apply/import/state_rm | string | none | no | Use a built-in command without additional configuration. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported | #### Built-In Command With Extra Args + A map from string to `extra_args` for a built-in command with extra arguments. + ```yaml - init: extra_args: [arg1, arg2] @@ -484,79 +516,88 @@ A map from string to `extra_args` for a built-in command with extra arguments. - state_rm: extra_args: [arg1, arg2] ``` + | Key | Type | Default | Required | Description | |---------------------------------|------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | init/plan/apply/import/state_rm | map[`extra_args` -> array[string]] | none | no | Use a built-in command and append `extra_args`. Only `init`, `plan`, `apply`, `import` and `state_rm` are supported as keys and only `extra_args` is supported as a value | #### Custom `run` Command + A custom command can be written in 2 ways Compact: + ```yaml - run: custom-command arg1 arg2 ``` + | Key | Type | Default | Required | Description | |-----|--------|---------|----------|----------------------| | run | string | none | no | Run a custom command | Full + ```yaml -- run: +- run: command: custom-command arg1 arg2 output: show ``` + | Key | Type | Default | Required | Description | |-----|--------------------------------------------------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | run | map[string -> string] | none | no | Run a custom command | | run.command | string | none | yes | Shell command to run | -| run.output | string | "show" | no | How to post-process the output of this command when posted in the PR comment. The options are
* `show` - preserve the full output
* `hide` - hide output from comment (still visible in the real-time streaming output)
* `strip_refreshing` - hide all output up until and including the last line containing "Refreshing...". This matches the behavior of the built-in `plan` command | +| run.output | string | "show" | no | How to post-process the output of this command when posted in the PR comment. The options are
*`show` - preserve the full output
* `hide` - hide output from comment (still visible in the real-time streaming output)
* `strip_refreshing` - hide all output up until and including the last line containing "Refreshing...". This matches the behavior of the built-in `plan` command | ::: tip Notes -* `run` steps in the main `workflow` are executed with the following environment variables: + +* `run` steps in the main `workflow` are executed with the following environment variables: note: these variables are not available to `pre` or `post` workflows - * `WORKSPACE` - The Terraform workspace used for this project, ex. `default`. + * `WORKSPACE` - The Terraform workspace used for this project, ex. `default`. NOTE: if the step is executed before `init` then Atlantis won't have switched to this workspace yet. - * `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`. - * `DIR` - Absolute path to the current directory. - * `PLANFILE` - Absolute path to the location where Atlantis expects the plan to + * `ATLANTIS_TERRAFORM_VERSION` - The version of Terraform used for this project, ex. `0.11.0`. + * `DIR` - Absolute path to the current directory. + * `PLANFILE` - Absolute path to the location where Atlantis expects the plan to either be generated (by plan) or already exist (if running apply). Can be used to override the built-in `plan`/`apply` commands, ex. `run: terraform plan -out $PLANFILE`. - * `SHOWFILE` - Absolute path to the location where Atlantis expects the plan in json format to + * `SHOWFILE` - Absolute path to the location where Atlantis expects the plan in json format to either be generated (by show) or already exist (if running policy checks). Can be used to override the built-in `plan`/`apply` commands, ex. `run: terraform show -json $PLANFILE > $SHOWFILE`. - * `POLICYCHECKFILE` - Absolute path to the location of policy check output if Atlantis runs policy checks. + * `POLICYCHECKFILE` - Absolute path to the location of policy check output if Atlantis runs policy checks. See [policy checking](policy-checking.md#data-for-custom-run-steps) for information of data structure. - * `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`. - * `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`. - * `HEAD_REPO_NAME` - Name of the repository that is getting merged into the base repository, ex. `atlantis`. - * `HEAD_REPO_OWNER` - Owner of the repository that is getting merged into the base repository, ex. `acme-corp`. - * `HEAD_BRANCH_NAME` - Name of the head branch of the pull request (the branch that is getting merged into the base) - * `HEAD_COMMIT` - The sha256 that points to the head of the branch that is being pull requested into the base. If the pull request is from Bitbucket Cloud the string will only be 12 characters long because Bitbucket Cloud truncates its commit IDs. - * `BASE_BRANCH_NAME` - Name of the base branch of the pull request (the branch that the pull request is getting merged into) - * `PROJECT_NAME` - Name of the project configured in `atlantis.yaml`. If no project name is configured this will be an empty string. - * `PULL_NUM` - Pull request number or ID, ex. `2`. - * `PULL_URL` - Pull request URL, ex. `https://github.com/runatlantis/atlantis/pull/2`. - * `PULL_AUTHOR` - Username of the pull request author, ex. `acme-user`. - * `REPO_REL_DIR` - The relative path of the project in the repository. For example if your project is in `dir1/dir2/` then this will be set to `"dir1/dir2"`. If your project is at the root this will be `"."`. - * `USER_NAME` - Username of the VCS user running command, ex. `acme-user`. During an autoplan, the user will be the Atlantis API user, ex. `atlantis`. - * `COMMENT_ARGS` - Any additional flags passed in the comment on the pull request. Flags are separated by commas and + * `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`. + * `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`. + * `HEAD_REPO_NAME` - Name of the repository that is getting merged into the base repository, ex. `atlantis`. + * `HEAD_REPO_OWNER` - Owner of the repository that is getting merged into the base repository, ex. `acme-corp`. + * `HEAD_BRANCH_NAME` - Name of the head branch of the pull request (the branch that is getting merged into the base) + * `HEAD_COMMIT` - The sha256 that points to the head of the branch that is being pull requested into the base. If the pull request is from Bitbucket Cloud the string will only be 12 characters long because Bitbucket Cloud truncates its commit IDs. + * `BASE_BRANCH_NAME` - Name of the base branch of the pull request (the branch that the pull request is getting merged into) + * `PROJECT_NAME` - Name of the project configured in `atlantis.yaml`. If no project name is configured this will be an empty string. + * `PULL_NUM` - Pull request number or ID, ex. `2`. + * `PULL_URL` - Pull request URL, ex. `https://github.com/runatlantis/atlantis/pull/2`. + * `PULL_AUTHOR` - Username of the pull request author, ex. `acme-user`. + * `REPO_REL_DIR` - The relative path of the project in the repository. For example if your project is in `dir1/dir2/` then this will be set to `"dir1/dir2"`. If your project is at the root this will be `"."`. + * `USER_NAME` - Username of the VCS user running command, ex. `acme-user`. During an autoplan, the user will be the Atlantis API user, ex. `atlantis`. + * `COMMENT_ARGS` - Any additional flags passed in the comment on the pull request. Flags are separated by commas and every character is escaped, ex. `atlantis plan -- arg1 arg2` will result in `COMMENT_ARGS=\a\r\g\1,\a\r\g\2`. * A custom command will only terminate if all output file descriptors are closed. Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during the terraform run) when its output is redirected to a different location. For example, Atlantis -will execute a custom script containing the following code to create a SSH tunnel correctly: +will execute a custom script containing the following code to create a SSH tunnel correctly: `ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1`. Without the redirect, the script would block the Atlantis workflow. -* If a workflow step returns a non-zero exit code, the workflow will stop. +* If a workflow step returns a non-zero exit code, the workflow will stop. ::: #### Environment Variable `env` Command + The `env` command allows you to set environment variables that will be available to all steps defined **below** the `env` step. You can set hard coded values via the `value` key, or set dynamic values via the `command` key which allows you to run any command and uses the output as the environment variable value. + ```yaml - env: name: ENV_NAME @@ -565,6 +606,7 @@ as the environment variable value. name: ENV_NAME_2 command: 'echo "dynamic-value-$(date)"' ``` + | Key | Type | Default | Required | Description | |-----------------|-----------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------| | env | map[string -> string] | none | no | Set environment variables for subsequent steps | @@ -573,16 +615,20 @@ as the environment variable value. | env.command | string | none | no | Set the value of the environment variable to the output of a command. Cannot be set at the same time as `value` | ::: tip Notes + * `env` `command`'s can use any of the built-in environment variables available - to `run` commands. + to `run` commands. ::: #### Multiple Environment Variables `multienv` Command + The `multienv` command allows you to set dynamic number of multiple environment variables that will be available to all steps defined **below** the `multienv` step. + ```yaml - multienv: custom-command ``` + | Key | Type | Default | Required | Description | |----------|--------|---------|----------|--------------------------------------------------------------------------------| | multienv | string | none | no | Run a custom command and add set environment variables according to the result | @@ -593,6 +639,7 @@ EnvVar1Name=value1,EnvVar2Name=value2,EnvVar3Name=value3 The name-value pairs in the result are added as environment variables if success is true otherwise the workflow execution stops with error and the errorMessage is getting displayed. ::: tip Notes + * `multienv` `command`'s can use any of the built-in environment variables available - to `run` commands. + to `run` commands. ::: diff --git a/runatlantis.io/docs/deployment.md b/runatlantis.io/docs/deployment.md index 19a84bd848..47de9462e1 100644 --- a/runatlantis.io/docs/deployment.md +++ b/runatlantis.io/docs/deployment.md @@ -1,20 +1,23 @@ # Deployment + This page covers getting Atlantis up and running in your infrastructure. ::: tip Prerequisites + * You have created [access credentials](access-credentials.md) for your Atlantis user * You have created a [webhook secret](webhook-secrets.md) ::: -[[toc]] - ## Architecture Overview + ### Runtime + Atlantis is a simple [Go](https://golang.org/) app. It receives webhooks from your Git host and executes Terraform commands locally. There is an official Atlantis [Docker image](https://ghcr.io/runatlantis/atlantis). ### Routing + Atlantis and your Git host need to be able to route and communicate with one another. Your Git host needs to be able to send webhooks to Atlantis and Atlantis needs to be able to make API calls to your Git host. If you're using a public Git host like github.com, gitlab.com, gitea.com, bitbucket.org, or dev.azure.com then you'll need to @@ -24,6 +27,7 @@ If you're using a private Git host like GitHub Enterprise, GitLab Enterprise, se Bitbucket Server, then Atlantis needs to be routable from the private host and Atlantis will need to be able to route to the private host. ### Data + Atlantis has no external database. Atlantis stores Terraform plan files on disk. If Atlantis loses that data in between a `plan` and `apply` cycle, then users will have to re-run `plan`. Because of this, you may want to provision a persistent disk @@ -32,6 +36,7 @@ for Atlantis. ## Deployment Pick your deployment type: + * [Kubernetes Helm Chart](#kubernetes-helm-chart) * [Kubernetes Manifests](#kubernetes-manifests) * [Kubernetes Kustomize](#kubernetes-kustomize) @@ -41,21 +46,27 @@ Pick your deployment type: * [Docker](#docker) * [Roll Your Own](#roll-your-own) - ### Kubernetes Helm Chart + Atlantis has an [official Helm chart](https://github.com/runatlantis/helm-charts/tree/main/charts/atlantis) To install: + 1. Add the runatlantis helm chart repository to helm + ```bash helm repo add runatlantis https://runatlantis.github.io/helm-charts ``` + 1. `cd` into a directory where you're going to configure your Atlantis Helm chart 1. Create a `values.yaml` file by running + ```bash helm inspect values runatlantis/atlantis > values.yaml ``` + 1. Edit `values.yaml` and add your access credentials and webhook secret + ```yaml # for example github: @@ -63,28 +74,33 @@ To install: token: bar secret: baz ``` + 1. Edit `values.yaml` and set your `orgAllowlist` (see [Repo Allowlist](server-configuration.md#repo-allowlist) for more information) + ```yaml orgAllowlist: github.com/runatlantis/* ``` - **Note**: For helm chart version < `4.0.2`, `orgWhitelist` must be used instead. + + **Note**: For helm chart version < `4.0.2`, `orgWhitelist` must be used instead. 1. Configure any other variables (see [Atlantis Helm Chart: Customization](https://github.com/runatlantis/helm-charts#customization) for documentation) 1. Run + ```sh helm install atlantis runatlantis/atlantis -f values.yaml ``` If you are using helm v2, run: + ```sh helm install -f values.yaml runatlantis/atlantis ``` - Atlantis should be up and running in minutes! See [Next Steps](#next-steps) for what to do next. ### Kubernetes Manifests + If you'd like to use a raw Kubernetes manifest, we offer either a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or a [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) with persistent storage. @@ -94,16 +110,19 @@ or you upgrade Atlantis, you won't lose plans that haven't been applied. If you do lose that data, you just need to run `atlantis plan` again so it's not the end of the world. Regardless of whether you choose a Deployment or StatefulSet, first create a Secret with the webhook secret and access token: + ```bash echo -n "yourtoken" > token echo -n "yoursecret" > webhook-secret kubectl create secret generic atlantis-vcs --from-file=token --from-file=webhook-secret ``` + ::: tip Note If you're using Bitbucket Cloud then there is no webhook secret since it's not supported. ::: Next, edit the manifests below as follows: + 1. Replace `` in `image: ghcr.io/runatlantis/atlantis:` with the most recent version from [GitHub: Atlantis latest release](https://github.com/runatlantis/atlantis/releases/latest). * NOTE: You never want to run with `:latest` because if your Pod moves to a new node, Kubernetes will pull the latest image and you might end up upgrading Atlantis by accident! @@ -126,6 +145,7 @@ for your Terraform repos. See [--repo-allowlist](server-configuration.md#repo-al 2. Delete all the `ATLANTIS_GH_*`, `ATLANTIS_GITLAB_*`, `ATLANTIS_GITEA_*`, and `ATLANTIS_BITBUCKET_*` environment variables. #### StatefulSet Manifest +
Show... @@ -290,10 +310,11 @@ spec: selector: app.kubernetes.io/name: atlantis ``` -
+ #### Deployment Manifest +
Show... @@ -438,9 +459,11 @@ spec: selector: app.kubernetes.io/name: atlantis ``` +
#### Routing and SSL + The manifests above create a Kubernetes `Service` of `type: ClusterIP` which isn't accessible outside your cluster. Depending on how you're doing routing into Kubernetes, you may want to use a Service of `type: LoadBalancer` so that Atlantis is accessible to GitHub/GitLab and your internal users. @@ -458,6 +481,7 @@ A `kustomization.yaml` file is provided in the directory `kustomize/`, so you ma You will need to provide a secret (with the default name of `atlantis-vcs`) to configure Atlantis with access credentials for your remote repositories. Example: + ```yaml bases: - github.com/runatlantis/atlantis//kustomize @@ -483,7 +507,6 @@ patchesStrategicMerge: #### Required - ```yaml ... containers: @@ -572,16 +595,19 @@ containers: ``` ### OpenShift + The Helm chart and Kubernetes manifests above are compatible with OpenShift, however you need to run with an additional environment variable: `HOME=/home/atlantis`. This is required because OpenShift runs Docker images with random user id's that use `/` as their home directory. ### AWS Fargate + If you'd like to run Atlantis on [AWS Fargate](https://aws.amazon.com/fargate/) check out the Atlantis module on the [Terraform Module Registry](https://registry.terraform.io/modules/terraform-aws-modules/atlantis/aws/latest) and then check out the [Next Steps](#next-steps). ### Google Kubernetes Engine (GKE) + You can run Atlantis on GKE using the [Helm chart](#kubernetes-helm-chart) or the [manifests](#kubernetes-manifests). There is also a set of full Terraform configurations that create a GKE Cluster, @@ -590,19 +616,23 @@ Cloud Storage Backend and TLS certs: [sethvargo atlantis-on-gke](https://github. Once you're done, see [Next Steps](#next-steps). ### Google Compute Engine (GCE) -Atlantis can be run on Google Compute Engine using a Terraform module that deploys it as a Docker container on a managed Compute Engine instance. + +Atlantis can be run on Google Compute Engine using a Terraform module that deploys it as a Docker container on a managed Compute Engine instance. This [Terraform module](https://registry.terraform.io/modules/runatlantis/atlantis/gce/latest) features the creation of a Cloud load balancer, a Container-Optimized OS-based VM, a persistent data disk, and a managed instance group. After it is deployed, see [Next Steps](#next-steps). ### Docker + Atlantis has an [official](https://ghcr.io/runatlantis/atlantis) Docker image: `ghcr.io/runatlantis/atlantis`. #### Customization + If you need to modify the Docker image that we provide, for instance to add the terragrunt binary, you can do something like this: 1. Create a custom docker file + ```dockerfile FROM ghcr.io/runatlantis/atlantis:{latest version} @@ -616,32 +646,37 @@ Additionally, the /docker-entrypoint.d/ directory offers a flexible option for i **Important Notice**: There is a critical update regarding the data directory in Atlantis. In versions prior to 0.26.0, the directory was configured to be accessible by the root user. However, with the transition to the atlantis user in newer versions, it is imperative to update the directory permissions accordingly in your current deployment when upgrading to a version later than 0.26.0. This step ensures seamless access and functionality for the atlantis user. 1. Build your Docker image + ```bash docker build -t {YOUR_DOCKER_ORG}/atlantis-custom . ``` 1. Run your image + ```bash docker run {YOUR_DOCKER_ORG}/atlantis-custom server --gh-user=GITHUB_USERNAME --gh-token=GITHUB_TOKEN ``` ### Microsoft Azure -The standard [Kubernetes Helm Chart](#kubernetes-helm-chart) should work fine on [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/intro-kubernetes). +The standard [Kubernetes Helm Chart](#kubernetes-helm-chart) should work fine on [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/intro-kubernetes). -Another option is [Azure Container Instances](https://docs.microsoft.com/en-us/azure/container-instances/). See this community member's [repo](https://github.com/jplane/atlantis-on-aci) or the new and more up-to-date [Terraform module](https://github.com/getindata/terraform-azurerm-atlantis) for install scripts and more information on running Atlantis on ACI. +Another option is [Azure Container Instances](https://docs.microsoft.com/en-us/azure/container-instances/). See this community member's [repo](https://github.com/jplane/atlantis-on-aci) or the new and more up-to-date [Terraform module](https://github.com/getindata/terraform-azurerm-atlantis) for install scripts and more information on running Atlantis on ACI. **Note on ACI Deployment:** Due to a bug in earlier Docker releases, Docker v23.0.0 or later is required for straightforward deployment. Alternatively, the Atlantis Docker image can be pushed to a private registry such as ACR and then used. ### Roll Your Own + If you want to roll your own Atlantis installation, you can get the `atlantis` binary from [GitHub](https://github.com/runatlantis/atlantis/releases) or use the [official Docker image](https://ghcr.io/runatlantis/atlantis). #### Startup Command + The exact flags to `atlantis server` depends on your Git host: ##### GitHub + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -652,6 +687,7 @@ atlantis server \ ``` ##### GitHub Enterprise + ```bash HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io atlantis server \ @@ -664,6 +700,7 @@ atlantis server \ ``` ##### GitLab + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -674,6 +711,7 @@ atlantis server \ ``` ##### GitLab Enterprise + ```bash HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io atlantis server \ @@ -686,6 +724,7 @@ atlantis server \ ``` ##### Gitea + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -697,6 +736,7 @@ atlantis server \ ``` ##### Bitbucket Cloud (bitbucket.org) + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -706,6 +746,7 @@ atlantis server \ ``` ##### Bitbucket Server (aka Stash) + ```bash BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990 atlantis server \ @@ -734,20 +775,20 @@ atlantis server \ ``` Where -- `$URL` is the URL that Atlantis can be reached at -- `$USERNAME` is the GitHub/GitLab/Gitea/Bitbucket/AzureDevops username you generated the token for -- `$TOKEN` is the access token you created. If you don't want this to be passed +* `$URL` is the URL that Atlantis can be reached at +* `$USERNAME` is the GitHub/GitLab/Gitea/Bitbucket/AzureDevops username you generated the token for +* `$TOKEN` is the access token you created. If you don't want this to be passed in as an argument for security reasons you can specify it in a config file (see [Configuration](server-configuration.md#environment-variables)) or as an environment variable: `ATLANTIS_GH_TOKEN` or `ATLANTIS_GITLAB_TOKEN` or `ATLANTIS_GITEA_TOKEN` or `ATLANTIS_BITBUCKET_TOKEN` or `ATLANTIS_AZUREDEVOPS_TOKEN` -- `$SECRET` is the random key you used for the webhook secret. +* `$SECRET` is the random key you used for the webhook secret. If you don't want this to be passed in as an argument for security reasons you can specify it in a config file (see [Configuration](server-configuration.md#environment-variables)) or as an environment variable: `ATLANTIS_GH_WEBHOOK_SECRET` or `ATLANTIS_GITLAB_WEBHOOK_SECRET` or `ATLANTIS_GITEA_WEBHOOK_SECRET` -- `$REPO_ALLOWLIST` is which repos Atlantis can run on, ex. +* `$REPO_ALLOWLIST` is which repos Atlantis can run on, ex. `github.com/runatlantis/*` or `github.enterprise.corp.com/*`. See [--repo-allowlist](server-configuration.md#repo-allowlist) for more details. @@ -758,5 +799,6 @@ restart it in case of failure. ::: ## Next Steps + * To ensure Atlantis is running, load its UI. By default Atlantis runs on port `4141`. * Now you're ready to add Webhooks to your repos. See [Configuring Webhooks](configuring-webhooks.md). diff --git a/runatlantis.io/docs/locking.md b/runatlantis.io/docs/locking.md index 65836d3b70..c75e2b3fce 100644 --- a/runatlantis.io/docs/locking.md +++ b/runatlantis.io/docs/locking.md @@ -1,4 +1,5 @@ # Locking + When `plan` is run, the directory and Terraform workspace are **Locked** until the pull request is merged or closed, or the plan is manually deleted. If another user attempts to `plan` for the same directory and workspace in a different pull request @@ -12,9 +13,8 @@ Which links them to the pull request that holds the lock. Only the directory in the repo and Terraform workspace are locked, not the whole repo. ::: -[[toc]] - ## Why + 1. Because `atlantis apply` is being done before the pull request is merged, after an apply your `main` branch does not represent the most up to date version of your infrastructure anymore. With locking, you can ensure that no other changes will be made until the @@ -30,6 +30,7 @@ but with the added ability to re-plan/apply multiple times if things don't work. will be made invalid after the in-progress plan is applied. ## Viewing Locks + To view locks, go to the URL that Atlantis is hosted at: ![Locks View](./images/locks-ui.png) @@ -41,6 +42,7 @@ You can click on a lock to view its details:

## Unlocking + The project and workspace will be automatically unlocked when the PR is merged or closed. To unlock the project and workspace without completing an `apply` and merging, comment `atlantis unlock` on the PR, @@ -59,6 +61,7 @@ to delete the lock. Once a plan is discarded, you'll need to run `plan` again prior to running `apply` when you go back to that pull request. ## Relationship to Terraform State Locking + Atlantis does not conflict with [Terraform State Locking](https://developer.hashicorp.com/terraform/language/state/locking). Under the hood, all Atlantis is doing is running `terraform plan` and `apply` and so all of the locking built in to those commands by Terraform isn't affected. diff --git a/runatlantis.io/docs/post-workflow-hooks.md b/runatlantis.io/docs/post-workflow-hooks.md index 0a63ab1f0b..91ba0b7aa7 100644 --- a/runatlantis.io/docs/post-workflow-hooks.md +++ b/runatlantis.io/docs/post-workflow-hooks.md @@ -6,8 +6,6 @@ workflows](custom-workflows.md#custom-run-command) in that they are run outside of Atlantis commands. Which means they do not surface their output back to the PR as a comment. -[[toc]] - ## Usage Post workflow hooks can only be specified in the Server-Side Repo Config under @@ -44,7 +42,6 @@ have finished. In this example we use a custom workflow to generate cost estimates for each workflow using [Infracost](https://www.infracost.io/docs/integrations/cicd/#cicd-integrations), then create a summary report after all workflows have completed. - ```yaml # repos.yaml workflows: @@ -102,6 +99,7 @@ command](custom-workflows.md#custom-run-command). | shellArgs | string | '-c' | no | The shell arguments to use for running the command | ::: tip Notes + * `run` commands are executed with the following environment variables: * `BASE_REPO_NAME` - Name of the repository that the pull request will be merged into, ex. `atlantis`. * `BASE_REPO_OWNER` - Owner of the repository that the pull request will be merged into, ex. `runatlantis`. diff --git a/runatlantis.io/docs/pre-workflow-hooks.md b/runatlantis.io/docs/pre-workflow-hooks.md index edcd4a0e83..dce3f2fe7d 100644 --- a/runatlantis.io/docs/pre-workflow-hooks.md +++ b/runatlantis.io/docs/pre-workflow-hooks.md @@ -9,8 +9,6 @@ workflows](custom-workflows.md#custom-run-command) in several ways. 2. Pre workflow hooks are run outside of Atlantis commands. Which means they do not surface their output back to the PR as a comment. -[[toc]] - ## Usage Pre workflow hooks can only be specified in the Server-Side Repo Config under the diff --git a/runatlantis.io/docs/repo-level-atlantis-yaml.md b/runatlantis.io/docs/repo-level-atlantis-yaml.md index aba096f311..3b41428c01 100644 --- a/runatlantis.io/docs/repo-level-atlantis-yaml.md +++ b/runatlantis.io/docs/repo-level-atlantis-yaml.md @@ -1,16 +1,17 @@ # Repo Level atlantis.yaml Config + An `atlantis.yaml` file specified at the root of a Terraform repo allows you to instruct Atlantis on the structure of your repo and set custom workflows. -[[toc]] - ## Do I need an atlantis.yaml file? + `atlantis.yaml` files are only required if you wish to customize some aspect of Atlantis. The default Atlantis config works for many users without changes. Read through the [use-cases](#use-cases) to determine if you need it. ## Enabling atlantis.yaml + By default, all repos are allowed to have an `atlantis.yaml` file, but some of the keys are restricted by default. @@ -20,6 +21,7 @@ keys by setting the `allowed_overrides` key there. See the [Server Side Repo Con 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) @@ -147,7 +149,9 @@ grep -P 'backend[\s]+"s3"' **/*.tf | ``` ## Use Cases + ### Disabling Autoplanning + ```yaml version: 3 projects: @@ -155,6 +159,7 @@ projects: autoplan: enabled: false ``` + This will stop Atlantis automatically running plan when `project1/` is updated in a pull request. @@ -193,7 +198,6 @@ Given the directory structure: If you want Atlantis to plan `project1/` whenever any `.tf` files under `module1/` change or any `.tf` or `.tfvars` files under `project1/` change you could use the following configuration: - ```yaml version: 3 projects: @@ -203,12 +207,14 @@ projects: ``` Note: + * `when_modified` uses the [`.dockerignore` syntax](https://docs.docker.com/engine/reference/builder/#dockerignore-file) * The paths are relative to the project's directory. * `when_modified` will be used by both automatic and manually run plans. * `when_modified` will continue to work for manually run plans even when autoplan is disabled. ### Supporting Terraform Workspaces + ```yaml version: 3 projects: @@ -217,34 +223,44 @@ projects: - dir: project1 workspace: production ``` + With the above config, when Atlantis determines that the configuration for the `project1` dir has changed, it will run plan for both the `staging` and `production` workspaces. If you want to `plan` or `apply` for a specific workspace you can use + ``` atlantis plan -w staging -d project1 ``` + and + ``` atlantis apply -w staging -d project1 ``` ### Using .tfvars files + See [Custom Workflow Use Cases: Using .tfvars files](custom-workflows.md#tfvars-files) ### Adding extra arguments to Terraform commands + See [Custom Workflow Use Cases: Adding extra arguments to Terraform commands](custom-workflows.md#adding-extra-arguments-to-terraform-commands) ### Custom init/plan/apply Commands + See [Custom Workflow Use Cases: Custom init/plan/apply Commands](custom-workflows.md#custom-init-plan-apply-commands) ### Terragrunt + See [Custom Workflow Use Cases: Terragrunt](custom-workflows.md#terragrunt) ### Running custom commands + See [Custom Workflow Use Cases: Running custom commands](custom-workflows.md#running-custom-commands) ### Terraform Versions + If you'd like to use a different version of Terraform than what is in Atlantis' `PATH` or is set by the `--default-tf-version` flag, then set the `terraform_version` key: @@ -258,7 +274,9 @@ projects: Atlantis will automatically download and use this version. ### Requiring Approvals For Production + In this example, we only want to require `apply` approvals for the `production` directory. + ```yaml version: 3 projects: @@ -268,12 +286,14 @@ projects: apply_requirements: [approved] import_requirements: [approved] ``` + :::warning `plan_requirements`, `apply_requirements` and `import_requirements` are restricted keys so this repo will need to be configured to be allowed to set this key. See [Server-Side Repo Config Use Cases](server-side-repo-config.md#repos-can-set-their-own-apply-an-applicable-subcommand). ::: ### Order of planning/applying + ```yaml version: 3 abort_on_execution_order_fail: true @@ -283,12 +303,13 @@ projects: - dir: project2 execution_order_group: 1 ``` + With this config above, Atlantis runs planning/applying for project2 first, then for project1. Several projects can have same `execution_order_group`. Any order in one group isn't guaranteed. `parallel_plan` and `parallel_apply` respect these order groups, so parallel planning/applying works -in each group one by one. +in each group one by one. -If any plan/apply fails and `abort_on_execution_order_fail` is set to true on a repo level, all the +If any plan/apply fails and `abort_on_execution_order_fail` is set to true on a repo level, all the following groups will be aborted. For this example, if project2 fails then project1 will not run. Execution order groups are useful when you have dependencies between projects. However, they are only applicable in the case where @@ -296,6 +317,7 @@ you initiate a global apply for all of your projects, i.e `atlantis apply`. If y Thus, the `depends_on` key is more useful in this case. and can be used in conjunction with execution order groups. The following configuration is an example of how to use execution order groups and depends_on together to enforce dependencies between projects. + ```yaml version: 3 projects: @@ -323,6 +345,7 @@ projects: workspace: production workflow: infra ``` + the `depends_on` feature will make sure that `production` is not applied before `staging` for example. ::: tip @@ -331,11 +354,14 @@ What Happens if one or more project's dependencies are not applied? If there's one or more projects in the dependency list which is not in applied status, users will see an error message like this: `Can't apply your project unless you apply its dependencies` ::: + ### Autodiscovery Config + ```yaml autodiscover: mode: "auto" ``` + The above is the default configuration for `autodiscover.mode`. When `autodiscover.mode` is auto, projects will be discovered only if the repo has no `projects` configured. @@ -343,6 +369,7 @@ projects will be discovered only if the repo has no `projects` configured. autodiscover: mode: "disabled" ``` + With the config above, Atlantis will never try to discover projects, even when there are no `projects` configured. This is useful if dynamically generating Atlantis config in pre_workflow hooks. See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-generation). @@ -351,6 +378,7 @@ See [Dynamic Repo Config Generation](pre-workflow-hooks.md#dynamic-repo-config-g autodiscover: mode: "enabled" ``` + With the config above, Atlantis will unconditionally try to discover projects based on modified_files, even when the directory of the project is missing from the configured `projects` in the repo configuration. If a discovered project has the same directory as a project which was manually configured in `projects`, @@ -360,10 +388,13 @@ Use this feature when some projects require specific configuration in a repo wit it's still desirable for Atlantis to plan/apply for projects not enumerated in the config. ### Custom Backend Config + See [Custom Workflow Use Cases: Custom Backend Config](custom-workflows.md#custom-backend-config) ## Reference + ### Top-Level Keys + ```yaml version: 3 automerge: false @@ -372,6 +403,7 @@ projects: workflows: allowed_regexp_prefixes: ``` + | Key | Type | Default | Required | Description | |-------------------------------|--------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------| | version | int | none | **yes** | This key is required and must be set to `3`. | @@ -382,6 +414,7 @@ allowed_regexp_prefixes: | allowed_regexp_prefixes | array[string] | `[]` | no | Lists the allowed regexp prefixes to use when the [`--enable-regexp-cmd`](server-configuration.md#enable-regexp-cmd) flag is used. | ### Project + ```yaml name: myname branch: /mybranch/ @@ -423,10 +456,12 @@ Atlantis supports this but requires the `name` key to be specified. See [Custom ::: ### Autoplan + ```yaml enabled: true when_modified: ["*.tf", "terragrunt.hcl", ".terraform.lock.hcl"] ``` + | Key | Type | Default | Required | Description | |-----------------------|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | enabled | boolean | `true` | no | Whether autoplanning is enabled for this project. | diff --git a/runatlantis.io/docs/requirements.md b/runatlantis.io/docs/requirements.md index 3eaf9552f1..0929387bad 100644 --- a/runatlantis.io/docs/requirements.md +++ b/runatlantis.io/docs/requirements.md @@ -1,10 +1,10 @@ # Requirements + Atlantis works with most Git hosts and Terraform setups. Read on to confirm it works with yours. -[[toc]] - ## Git Host + Atlantis integrates with the following Git hosts: * GitHub (public, private or enterprise) @@ -15,6 +15,7 @@ Atlantis integrates with the following Git hosts: * Azure DevOps ## Terraform State + Atlantis supports all backend types **except for local state**. We don't support local state because Atlantis does not have permanent storage and it doesn't commit the new statefile back to version control. @@ -25,9 +26,11 @@ storage from Terraform Cloud. This is fully supported by Atlantis. ::: ## Repository Structure + Atlantis supports any Terraform repository structure, for example: ### Single Terraform Project At Repo Root + ``` . ├── main.tf @@ -35,6 +38,7 @@ Atlantis supports any Terraform repository structure, for example: ``` ### Multiple Project Folders + ``` . ├── project1 @@ -46,6 +50,7 @@ Atlantis supports any Terraform repository structure, for example: ``` ### Modules + ``` . ├── project1 @@ -56,10 +61,12 @@ Atlantis supports any Terraform repository structure, for example:    ├── main.tf └── ... ``` + With modules, if you want `project1` automatically planned when `module1` is modified you need to create an `atlantis.yaml` file. See [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#configuring-planning) for more details. -### Terraform Workspaces +### Terraform Workspaces + *See [Terraform's docs](https://developer.hashicorp.com/terraform/language/state/workspaces) if you are unfamiliar with workspaces.* If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an @@ -67,24 +74,29 @@ If you're using Terraform `>= 0.9.0`, Atlantis supports workspaces through an (see [atlantis.yaml Use Cases](repo-level-atlantis-yaml.md#supporting-terraform-workspaces) for more details) ### .tfvars Files + ``` . ├── production.tfvars │── staging.tfvars └── main.tf ``` + For Atlantis to be able to plan automatically with `.tfvars files`, you need to create an `atlantis.yaml` file to tell it to use `-var-file={YOUR_FILE}`. See [atlantis.yaml Use Cases](custom-workflows.md#tfvars-files) for more details. ### Multiple Repos + Atlantis supports multiple repos as well–as long as there is a webhook configured for each repo. ## Terraform Versions + Atlantis supports all Terraform versions (including 0.12) and can be configured to use different versions for different repositories/projects. See [Terraform Versions](terraform-versions.md). ## Next Steps + * If your Terraform setup meets the Atlantis requirements, continue the installation guide and set up your [Git Host Access Credentials](access-credentials.md) diff --git a/runatlantis.io/docs/security.md b/runatlantis.io/docs/security.md index 959f386764..514285c822 100644 --- a/runatlantis.io/docs/security.md +++ b/runatlantis.io/docs/security.md @@ -1,13 +1,16 @@ # Security -[[toc]] + ## Exploits + Because you usually run Atlantis on a server with credentials that allow access to your infrastructure it's important that you deploy Atlantis securely. Atlantis could be exploited by + * An attacker submitting a pull request that contains a malicious Terraform file that uses a malicious provider or an [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source) that Atlantis then runs `terraform plan` on (which it does automatically unless you've turned off automatic plans). * Running `terraform apply` on a malicious Terraform file with [local-exec](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec) + ```tf resource "null_resource" "null" { provisioner "local-exec" { @@ -15,10 +18,12 @@ Atlantis could be exploited by } } ``` + * Running malicious custom build commands specified in an `atlantis.yaml` file. Atlantis uses the `atlantis.yaml` file from the pull request branch, **not** `main`. * Someone adding `atlantis plan/apply` comments on your valid pull requests causing terraform to run when you don't want it to. ## Bitbucket Cloud (bitbucket.org) + ::: danger Bitbucket Cloud does not support webhook secrets. This could allow attackers to spoof requests from Bitbucket. Ensure you are allowing only Bitbucket IPs. ::: @@ -33,16 +38,21 @@ To prevent this, allowlist [Bitbucket's IP addresses](https://confluence.atlassi (see Outbound IPv4 addresses). ## Mitigations + ### Don't Use On Public Repos + Because anyone can comment on public pull requests, even with all the security mitigations available, it's still dangerous to run Atlantis on public repos without proper configuration of the security settings. ### Don't Use `--allow-fork-prs` + If you're running on a public repo (which isn't recommended, see above) you shouldn't set `--allow-fork-prs` (defaults to false) because anyone can open up a pull request from their fork to your repo. ### `--repo-allowlist` + Atlantis requires you to specify a allowlist of repositories it will accept webhooks from via the `--repo-allowlist` flag. For example: + * Specific repositories: `--repo-allowlist=github.com/runatlantis/atlantis,github.com/runatlantis/atlantis-tests` * Your whole organization: `--repo-allowlist=github.com/runatlantis/*` * Every repository in your GitHub Enterprise install: `--repo-allowlist=github.yourcompany.com/*` @@ -52,12 +62,14 @@ For example: This flag ensures your Atlantis install isn't being used with repositories you don't control. See `atlantis server --help` for more details. ### Protect Terraform Planning + If attackers submitting pull requests with malicious Terraform code is in your threat model then you must be aware that `terraform apply` approvals are not enough. It is possible to run malicious code in a `terraform plan` using the [`external` data source](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/data_source) or by specifying a malicious provider. This code could then exfiltrate your credentials. To prevent this, you could: + 1. Bake providers into the Atlantis image or host and deny egress in production. 1. Implement the provider registry protocol internally and deny public egress, that way you control who has write access to the registry. 1. Modify your [server-side repo configuration](server-side-repo-config.md)'s `plan` step to validate against the @@ -65,13 +77,15 @@ To prevent this, you could: requiring a "thumbs-up" on the PR before allowing the `plan` to continue. Conftest could be of use here. ### `--var-file-allowlist` + The files on your Atlantis install may be accessible as [variable definition files](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files) -from pull requests by adding +from pull requests by adding `atlantis plan -- -var-file=/path/to/file` comments. To mitigate this security risk, Atlantis has limited such access only to the files allowlisted by the `--var-file-allowlist` flag. If this argument is not provided, it defaults to Atlantis' data directory. ### Webhook Secrets + Atlantis should be run with Webhook secrets set via the `$ATLANTIS_GH_WEBHOOK_SECRET`/`$ATLANTIS_GITLAB_WEBHOOK_SECRET` environment variables. Even with the `--repo-allowlist` flag set, without a webhook secret, attackers could make requests to Atlantis posing as a repository that is allowlisted. Webhook secrets ensure that the webhook requests are actually coming from your VCS provider (GitHub or GitLab). @@ -81,17 +95,20 @@ If you are using Azure DevOps, instead of webhook secrets add a [basic username ::: ### Azure DevOps Basic Authentication + Azure DevOps supports sending a basic authentication header in all webhook events. This requires using an HTTPS URL for your webhook location. ### SSL/HTTPS + If you're using webhook secrets but your traffic is over HTTP then the webhook secrets could be stolen. Enable SSL/HTTPS using the `--ssl-cert-file` and `--ssl-key-file` flags. ### Enable Authentication on Atlantis Web Server + It is very recommended to enable authentication in the web service. Enable BasicAuth using the `--web-basic-auth=true` and setup a username and a password using `--web-username=yourUsername` and `--web-password=yourPassword` flags. -You can also pass these as environment variables `ATLANTIS_WEB_BASIC_AUTH=true` `ATLANTIS_WEB_USERNAME=yourUsername` and `ATLANTIS_WEB_PASSWORD=yourPassword`. +You can also pass these as environment variables `ATLANTIS_WEB_BASIC_AUTH=true` `ATLANTIS_WEB_USERNAME=yourUsername` and `ATLANTIS_WEB_PASSWORD=yourPassword`. :::tip Tip We do encourage the usage of complex passwords in order to prevent basic bruteforcing attacks. diff --git a/runatlantis.io/docs/server-configuration.md b/runatlantis.io/docs/server-configuration.md index 5adc1fc8ac..ebdb5c2935 100644 --- a/runatlantis.io/docs/server-configuration.md +++ b/runatlantis.io/docs/server-configuration.md @@ -1,12 +1,12 @@ # Server Configuration + This page explains how to configure the `atlantis server` command. Configuration to `atlantis server` can be specified via command line flags, environment variables, a config file or a mix of the three. -[[toc]] - ## Environment Variables + All flags can be specified as environment variables. 1. Take the flag name, ex. `--gh-user` @@ -24,11 +24,13 @@ The flag `--atlantis-url` is set by the environment variable `ATLANTIS_ATLANTIS_ ::: ## Config File + All flags can also be specified via a YAML config file. To use a YAML config file, run `atlantis server --config /path/to/config.yaml`. The keys of your config file should be the same as the flag names, ex. + ```yaml gh-token: ... log-level: ... @@ -40,40 +42,49 @@ The `--config` config file is only used as an alternate way of setting `atlantis ::: ## Precedence + Values are chosen in this order: + 1. Flags 1. Environment Variables 1. Config File - ## Flags + ### `--allow-commands` + ```bash atlantis server --allow-commands=version,plan,apply,unlock,approve_policies # or ATLANTIS_ALLOW_COMMANDS='version,plan,apply,unlock,approve_policies' ``` + List of allowed commands to be run on the Atlantis server, Defaults to `version,plan,apply,unlock,approve_policies` Notes: - * Accepts a comma separated list, ex. `command1,command2`. - * `version`, `plan`, `apply`, `unlock`, `approve_policies`, `import`, `state` and `all` are available. - * `all` is a special keyword that allows all commands. If pass `all` then all other commands will be ignored. + +* Accepts a comma separated list, ex. `command1,command2`. +* `version`, `plan`, `apply`, `unlock`, `approve_policies`, `import`, `state` and `all` are available. +* `all` is a special keyword that allows all commands. If pass `all` then all other commands will be ignored. ### `--allow-draft-prs` + ```bash atlantis server --allow-draft-prs # or ATLANTIS_ALLOW_DRAFT_PRS=true ``` + Respond to pull requests from draft prs. Defaults to `false`. ### `--allow-fork-prs` + ```bash atlantis server --allow-fork-prs # or ATLANTIS_ALLOW_FORK_PRS=true ``` + Respond to pull requests from forks. Defaults to `false`. :::warning SECURITY WARNING @@ -85,33 +96,40 @@ Values are chosen in this order: ::: ### `--api-secret` + ```bash atlantis server --api-secret="secret" # or (recommended) ATLANTIS_API_SECRET="secret" ``` + Required secret used to validate requests made to the [`/api/*` endpoints](api-endpoints.md). ### `--atlantis-url` + ```bash atlantis server --atlantis-url="https://my-domain.com:9090/basepath" # or ATLANTIS_ATLANTIS_URL=https://my-domain.com:9090/basepath ``` + Specify the URL that Atlantis is accessible from. Used in the Atlantis UI and in links from pull request comments. Defaults to `http://$(hostname):$port` where `$port` is from the [`--port`](#port) flag. Supports a basepath if you're hosting Atlantis under a path. Notes: - * If a load balancer with a non http/https port (not the one defined in the `--port` flag) is used, update the URL to include the port like in the example above. - * This URL is used as the `details` link next to each atlantis job to view the job's logs. + +* If a load balancer with a non http/https port (not the one defined in the `--port` flag) is used, update the URL to include the port like in the example above. +* This URL is used as the `details` link next to each atlantis job to view the job's logs. ### `--autodiscover-mode` + ```bash atlantis server --autodiscover-mode="" # 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. @@ -123,40 +141,45 @@ Values are chosen in this order: When set to `disabled` projects will never be discovered, even if there are no projects configured in the repo config. ### `--automerge` + ```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. ### `--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' ``` + List of file patterns that Atlantis will use to check if a directory contains modified files that should trigger project planning. 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 + +* 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. +* 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: - * 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. @@ -202,8 +225,8 @@ 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 @@ -217,35 +240,43 @@ and set `--autoplan-modules` to `false`. ::: ### `--azuredevops-hostname` + ```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`. ### `--azuredevops-token` + ```bash atlantis server --azuredevops-token="RandomStringProducedByAzureDevOps" # or (recommended) ATLANTIS_AZUREDEVOPS_TOKEN="RandomStringProducedByAzureDevOps" ``` + Azure DevOps token of API user. ### `--azuredevops-user` + ```bash atlantis server --azuredevops-user="username@example.com" # or ATLANTIS_AZUREDEVOPS_USER="username@example.com" ``` + Azure DevOps username of API user. ### `--azuredevops-webhook-password` + ```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)). @@ -258,45 +289,55 @@ and set `--autoplan-modules` to `false`. ::: ### `--azuredevops-webhook-user` + ```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. ### `--bitbucket-base-url` + ```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`. ### `--bitbucket-token` + ```bash atlantis server --bitbucket-token="token" # or (recommended) ATLANTIS_BITBUCKET_TOKEN="token" ``` + Bitbucket app password of API user. ### `--bitbucket-user` + ```bash atlantis server --bitbucket-user="myuser" # or ATLANTIS_BITBUCKET_USER="myuser" ``` + Bitbucket username of API user. ### `--bitbucket-webhook-secret` + ```bash atlantis server --bitbucket-webhook-secret="secret" # or (recommended) ATLANTIS_BITBUCKET_WEBHOOK_SECRET="secret" ``` + Secret used to validate Bitbucket webhooks. Only Bitbucket Server supports webhook secrets. For Bitbucket.org, see [Security](security.md#bitbucket-cloud-bitbucket-org) for mitigations. @@ -306,37 +347,45 @@ and set `--autoplan-modules` to `false`. ::: ### `--checkout-depth` + ```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. ### `--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. ### `--config` + ```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. ### `--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) @@ -346,98 +395,120 @@ and set `--autoplan-modules` to `false`. 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-version` + ```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. ### `--disable-apply-all` + ```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-autoplan` + ```bash atlantis server --disable-autoplan # or ATLANTIS_DISABLE_AUTOPLAN=true ``` + Disable atlantis auto planning. ### `--disable-autoplan-label` + ```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. If `disable-autoplan` property is `true`, this flag has no effect. ### `--disable-markdown-folding` + ```bash atlantis server --disable-markdown-folding # or ATLANTIS_DISABLE_MARKDOWN_FOLDING=true ``` + Disable folding in markdown output using the `
` html tag. ### `--disable-repo-locking` + ```bash atlantis server --disable-repo-locking # or ATLANTIS_DISABLE_REPO_LOCKING=true ``` + Stops atlantis from locking projects and or workspaces when running terraform. ### `--disable-unlock-label` + ```bash atlantis server --disable-unlock-label do-not-unlock # or ATLANTIS_DISABLE_UNLOCK_LABEL="do-not-unlock" ``` + Stops atlantis from unlocking a pull request with this label. Defaults to "" (feature disabled). ### `--emoji-reaction` + ```bash atlantis server --emoji-reaction thumbsup # or ATLANTIS_EMOJI_REACTION=thumbsup ``` + The emoji reaction to use for marking processed comments. Currently supported on Azure DevOps, GitHub and GitLab. Defaults to `eyes`. ### `--enable-diff-markdown-format` + ```bash atlantis server --enable-diff-markdown-format # or ATLANTIS_ENABLE_DIFF_MARKDOWN_FORMAT=true ``` + Enable Atlantis to format Terraform plan output into a markdown-diff friendly format for color-coding purposes. Useful to enable for use with GitHub. ### `--enable-policy-checks` + ```bash atlantis server --enable-policy-checks # or ATLANTIS_ENABLE_POLICY_CHECKS=true ``` + Enables atlantis to run server side policies on the result of a terraform plan. Policies are defined in [server side repo config](server-side-repo-config.md#reference). ### `--enable-regexp-cmd` + ```bash atlantis server --enable-regexp-cmd # or ATLANTIS_ENABLE_REGEXP_CMD=true ``` + Enable Atlantis to use regular expressions to run plan/apply commands against defined project names when `-p` flag is passed with it. This can be used to run all defined projects (with the `name` key) in `atlantis.yaml` using `atlantis plan -p .*`. @@ -454,16 +525,19 @@ and set `--autoplan-modules` to `false`. ::: ### `--executable-name` + ```bash atlantis server --executable-name="atlantis" # or ATLANTIS_EXECUTABLE_NAME="atlantis" ``` + Comment command trigger executable name. Defaults to `atlantis`. This is useful when running multiple Atlantis servers against a single repository. ### `--fail-on-pre-workflow-hook-error` + ```bash atlantis server --fail-on-pre-workflow-hook-error # or @@ -473,35 +547,43 @@ and set `--autoplan-modules` to `false`. Fail and do not run the requested Atlantis command if any of the pre workflow hooks error. ### `--gitea-base-url` + ```bash atlantis server --gitea-base-url="http://your-gitea.corp:7990/basepath" # or ATLANTIS_GITEA_BASE_URL="http://your-gitea.corp:7990/basepath" ``` + Base URL of Gitea installation. Must include `http://` or `https://`. Defaults to `https://gitea.com` if left empty/absent. ### `--gitea-token` + ```bash atlantis server --gitea-token="token" # or (recommended) ATLANTIS_GITEA_TOKEN="token" ``` + Gitea app password of API user. ### `--gitea-user` + ```bash atlantis server --gitea-user="myuser" # or ATLANTIS_GITEA_USER="myuser" ``` + Gitea username of API user. ### `--gitea-webhook-secret` + ```bash atlantis server --gitea-webhook-secret="secret" # or (recommended) ATLANTIS_GITEA_WEBHOOK_SECRET="secret" ``` + Secret used to validate Gitea webhooks. ::: warning SECURITY WARNING @@ -510,32 +592,38 @@ and set `--autoplan-modules` to `false`. ::: ### `--gitea-page-size` + ```bash atlantis server --gitea-page-size=30 # or (recommended) ATLANTIS_GITEA_PAGE_SIZE=30 ``` + Number of items on a single page in Gitea paged responses. ::: warning Configuration dependent The default value conforms to the Gitea server's standard config setting: DEFAULT_PAGING_NUM - The highest valid value depends on the Gitea server's config setting: MAX_RESPONSE_ITEMS + The highest valid value depends on the Gitea server's config setting: MAX_RESPONSE_ITEMS ::: ### `--gh-allow-mergeable-bypass-apply` + ```bash atlantis server --gh-allow-mergeable-bypass-apply # or ATLANTIS_GH_ALLOW_MERGEABLE_BYPASS_APPLY=true ``` + Feature flag to enable ability to use `mergeable` mode with required apply status check. ### `--gh-app-id` + ```bash atlantis server --gh-app-id="00000" # or ATLANTIS_GH_APP_ID="00000" ``` + GitHub app ID. If set, GitHub authentication will be performed as [an installation](https://docs.github.com/en/rest/apps/installations). ::: tip @@ -555,11 +643,13 @@ and set `--autoplan-modules` to `false`. ::: ### `--gh-app-key` + ```bash atlantis server --gh-app-key="-----BEGIN RSA PRIVATE KEY-----(...)" # or ATLANTIS_GH_APP_KEY="-----BEGIN RSA PRIVATE KEY-----(...)" ``` + The PEM encoded private key for the GitHub App. ::: warning SECURITY WARNING @@ -567,44 +657,54 @@ and set `--autoplan-modules` to `false`. ::: ### `--gh-app-key-file` + ```bash atlantis server --gh-app-key-file="path/to/app-key.pem" # or ATLANTIS_GH_APP_KEY_FILE="path/to/app-key.pem" ``` + Path to a GitHub App PEM encoded private key file. If set, GitHub authentication will be performed as [an installation](https://docs.github.com/en/rest/apps/installations). ### `--gh-app-slug` + ```bash atlantis server --gh-app-slug="myappslug" # or ATLANTIS_GH_APP_SLUG="myappslug" ``` + A slugged version of GitHub app name shown in pull requests comments, etc (not `Atlantis App` but something like `atlantis-app`). Atlantis uses the value of this parameter to identify the comments it has left on GitHub pull requests. This is used for functions such as `--hide-prev-plan-comments`. You need to obtain this value from your GitHub app, one way is to go to your App settings and open "Public page" from the left sidebar. Your `--gh-app-slug` value will be the last part of the URL, e.g `https://github.com/apps/`. ### `--gh-hostname` + ```bash atlantis server --gh-hostname="my.github.enterprise.com" # or ATLANTIS_GH_HOSTNAME="my.github.enterprise.com" ``` + Hostname of your GitHub Enterprise installation. If using [GitHub.com](https://github.com), don't set. Defaults to `github.com`. ### `--gh-org` + ```bash atlantis server --gh-org="myorgname" # or ATLANTIS_GH_ORG="myorgname" ``` + GitHub organization name. Set to enable creating a private GitHub app for this organization. ### `--gh-team-allowlist` + ```bash atlantis server --gh-team-allowlist="myteam:plan, secteam:apply, DevOps Team:apply, DevOps Team:import" # or ATLANTIS_GH_TEAM_ALLOWLIST="myteam:plan, secteam:apply, DevOps Team:apply, DevOps Team:import" ``` + In versions v0.21.0 and later, the GitHub team name can be a name or a slug. In versions v0.20.1 and below, the Github team name required the case sensitive team name. @@ -619,27 +719,33 @@ and set `--autoplan-modules` to `false`. ::: ### `--gh-token` + ```bash atlantis server --gh-token="token" # or (recommended) ATLANTIS_GH_TOKEN="token" ``` + GitHub token of API user. ### `--gh-user` + ```bash atlantis server --gh-user="myuser" # or ATLANTIS_GH_USER="myuser" ``` + GitHub username of API user. ### `--gh-webhook-secret` + ```bash atlantis server --gh-webhook-secret="secret" # or (recommended) ATLANTIS_GH_WEBHOOK_SECRET="secret" ``` + Secret used to validate GitHub webhooks (see [GitHub: Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)). ::: warning SECURITY WARNING @@ -648,36 +754,44 @@ and set `--autoplan-modules` to `false`. ::: ### `--gitlab-hostname` + ```bash atlantis server --gitlab-hostname="my.gitlab.enterprise.com" # or ATLANTIS_GITLAB_HOSTNAME="my.gitlab.enterprise.com" ``` + Hostname of your GitLab Enterprise installation. If using [Gitlab.com](https://gitlab.com), don't set. Defaults to `gitlab.com`. ### `--gitlab-token` + ```bash atlantis server --gitlab-token="token" # or (recommended) ATLANTIS_GITLAB_TOKEN="token" ``` + GitLab token of API user. ### `--gitlab-user` + ```bash atlantis server --gitlab-user="myuser" # or ATLANTIS_GITLAB_USER="myuser" ``` + GitLab username of API user. ### `--gitlab-webhook-secret` + ```bash atlantis server --gitlab-webhook-secret="secret" # or (recommended) ATLANTIS_GITLAB_WEBHOOK_SECRET="secret" ``` + Secret used to validate GitLab webhooks. ::: warning SECURITY WARNING @@ -686,71 +800,86 @@ and set `--autoplan-modules` to `false`. ::: ### `--help` + ```bash atlantis server --help ``` + View help. ### `--hide-prev-plan-comments` + ```bash atlantis server --hide-prev-plan-comments # or ATLANTIS_HIDE_PREV_PLAN_COMMENTS=true ``` + Hide previous plan comments to declutter PRs. This is only supported in GitHub and GitLab currently. This is not enabled by default. When using Github App, you need to set `--gh-app-slug` to enable this feature. ### `--hide-unchanged-plan-comments` + ```bash atlantis server --hide-unchanged-plan-comments # or ATLANTIS_HIDE_UNCHANGED_PLAN_COMMENTS=true ``` + Remove no-changes plan comments from the pull request. This is useful when you have many projects and want to keep the pull request clean from useless comments. ### `--include-git-untracked-files` + ```bash atlantis server --include-git-untracked-files # or ATLANTIS_INCLUDE_GIT_UNTRACKED_FILES=true ``` + Include git untracked files in the Atlantis modified file list. Used for example with CDKTF pre-workflow hooks that dynamically generate Terraform files. ### `--locking-db-type` + ```bash atlantis server --locking-db-type="" # or ATLANTIS_LOCKING_DB_TYPE="" ``` + The locking database type to use for storing plan and apply locks. Defaults to `boltdb`. Notes: - * If set to `boltdb`, only one process may have access to the boltdb instance. - * If set to `redis`, then `--redis-host`, `--redis-port`, and `--redis-password` must be set. + +* If set to `boltdb`, only one process may have access to the boltdb instance. +* If set to `redis`, then `--redis-host`, `--redis-port`, and `--redis-password` must be set. ### `--log-level` + ```bash atlantis server --log-level="" # or ATLANTIS_LOG_LEVEL="" ``` + Log level. Defaults to `info`. ### `--markdown-template-overrides-dir` + ```bash atlantis server --markdown-template-overrides-dir="path/to/templates/" # or ATLANTIS_MARKDOWN_TEMPLATE_OVERRIDES_DIR="path/to/templates/" ``` + This will be available in v0.21.0. Directory where Atlantis will read in overrides for markdown templates used to render comments on pull requests. Markdown template overrides may be specified either in individual files, or all together in a single file. All template - override files _must_ have the `.tmpl` extension, otherwise they will not be parsed. + override files *must* have the `.tmpl` extension, otherwise they will not be parsed. Markdown templates which may have overrides can be found [here](https://github.com/runatlantis/atlantis/tree/main/server/events/templates) @@ -760,67 +889,83 @@ This is useful when you have many projects and want to keep the pull request cle Defaults to the atlantis home directory `/home/atlantis/.markdown_templates/` in `/$HOME/.markdown_templates`. ### `--parallel-apply` + ```bash atlantis server --parallel-apply # or ATLANTIS_PARALLEL_APPLY=true ``` + Whether to run apply operations in parallel. Defaults to `false`. Explicit declaration in [repo config](repo-level-atlantis-yaml.md#run-plans-and-applies-in-parallel) takes precedence. ### `--parallel-plan` + ```bash atlantis server --parallel-plan # or ATLANTIS_PARALLEL_PLAN=true ``` + Whether to run plan operations in parallel. Defaults to `false`. Explicit declaration in [repo config](repo-level-atlantis-yaml.md#run-plans-and-applies-in-parallel) takes precedence. ### `--parallel-pool-size` + ```bash atlantis server --parallel-pool-size=100 # or ATLANTIS_PARALLEL_POOL_SIZE=100 ``` + Max size of the wait group that runs parallel plans and applies (if enabled). Defaults to `15` ### `--port` + ```bash atlantis server --port=4141 # or ATLANTIS_PORT=4141 ``` + Port to bind to. Defaults to `4141`. ### `--quiet-policy-checks` + ```bash atlantis server --quiet-policy-checks # or ATLANTIS_QUIET_POLICY_CHECKS=true ``` + Exclude policy check comments from pull requests unless there's an actual error from conftest. This also excludes warnings. Defaults to `false`. ### `--redis-db` + ```bash atlantis server --redis-db=0 # or ATLANTIS_REDIS_DB=0 ``` + The Redis Database to use when using a Locking DB type of `redis`. Defaults to `0`. ### `--redis-host` + ```bash atlantis server --redis-host="localhost" # or ATLANTIS_REDIS_HOST="localhost" ``` + The Redis Hostname for when using a Locking DB type of `redis`. ### `--redis-insecure-skip-verify` + ```bash atlantis server --redis-insecure-skip-verify=false # or ATLANTIS_REDIS_INSECURE_SKIP_VERIFY=false ``` + Controls whether the Redis client verifies the Redis server's certificate chain and host name. If true, accepts any certificate presented by the server and any host name in that certificate. Defaults to `false`. ::: warning SECURITY WARNING @@ -828,82 +973,97 @@ This is useful when you have many projects and want to keep the pull request cle ::: ### `--redis-password` + ```bash atlantis server --redis-password="password123" # or (recommended) ATLANTIS_REDIS_PASSWORD="password123" ``` + The Redis Password for when using a Locking DB type of `redis`. ### `--redis-port` + ```bash atlantis server --redis-port=6379 # or ATLANTIS_REDIS_PORT=6379 ``` + The Redis Port for when using a Locking DB type of `redis`. Defaults to `6379`. ### `--redis-tls-enabled` + ```bash atlantis server --redis-tls-enabled=false # or ATLANTIS_REDIS_TLS_ENABLED=false ``` + Enables a TLS connection, with min version of 1.2, to Redis when using a Locking DB type of `redis`. Defaults to `false`. ### `--repo-allowlist` + ```bash # NOTE: Use single quotes to avoid shell expansion of *. atlantis server --repo-allowlist='github.com/myorg/*' # or ATLANTIS_REPO_ALLOWLIST='github.com/myorg/*' ``` + Atlantis requires you to specify an allowlist of repositories it will accept webhooks from. Notes: - * Accepts a comma separated list, ex. `definition1,definition2` - * Format is `{hostname}/{owner}/{repo}`, ex. `github.com/runatlantis/atlantis` - * `*` matches any characters, ex. `github.com/runatlantis/*` will match all repos in the runatlantis organization - * An entry beginning with `!` negates it, ex. `github.com/foo/*,!github.com/foo/bar` will match all github repos in the `foo` owner *except* `bar`. - * For Bitbucket Server: `{hostname}` is the domain without scheme and port, `{owner}` is the name of the project (not the key), and `{repo}` is the repo name - * User (not project) repositories take on the format: `{hostname}/{full name}/{repo}` (e.g., `bitbucket.example.com/Jane Doe/myatlantis` for username `jdoe` and full name `Jane Doe`, which is not very intuitive) - * For Azure DevOps the allowlist takes one of two forms: `{owner}.visualstudio.com/{project}/{repo}` or `dev.azure.com/{owner}/{project}/{repo}` - * Microsoft is in the process of changing Azure DevOps to the latter form, so it may be safest to always specify both formats in your repo allowlist for each repository until the change is complete. + +* Accepts a comma separated list, ex. `definition1,definition2` +* Format is `{hostname}/{owner}/{repo}`, ex. `github.com/runatlantis/atlantis` +* `*` matches any characters, ex. `github.com/runatlantis/*` will match all repos in the runatlantis organization +* An entry beginning with `!` negates it, ex. `github.com/foo/*,!github.com/foo/bar` will match all github repos in the `foo` owner *except* `bar`. +* For Bitbucket Server: `{hostname}` is the domain without scheme and port, `{owner}` is the name of the project (not the key), and `{repo}` is the repo name + * User (not project) repositories take on the format: `{hostname}/{full name}/{repo}` (e.g., `bitbucket.example.com/Jane Doe/myatlantis` for username `jdoe` and full name `Jane Doe`, which is not very intuitive) +* For Azure DevOps the allowlist takes one of two forms: `{owner}.visualstudio.com/{project}/{repo}` or `dev.azure.com/{owner}/{project}/{repo}` +* Microsoft is in the process of changing Azure DevOps to the latter form, so it may be safest to always specify both formats in your repo allowlist for each repository until the change is complete. Examples: - * Allowlist `myorg/repo1` and `myorg/repo2` on `github.com` - * `--repo-allowlist=github.com/myorg/repo1,github.com/myorg/repo2` - * Allowlist all repos under `myorg` on `github.com` - * `--repo-allowlist='github.com/myorg/*'` - * Allowlist all repos under `myorg` on `github.com`, excluding `myorg/untrusted-repo` - * `--repo-allowlist='github.com/myorg/*,!github.com/myorg/untrusted-repo'` - * Allowlist all repos in my GitHub Enterprise installation - * `--repo-allowlist='github.yourcompany.com/*'` - * Allowlist all repos under `myorg` project `myproject` on Azure DevOps - * `--repo-allowlist='myorg.visualstudio.com/myproject/*,dev.azure.com/myorg/myproject/*'` - * Allowlist all repositories - * `--repo-allowlist='*'` + +* Allowlist `myorg/repo1` and `myorg/repo2` on `github.com` + * `--repo-allowlist=github.com/myorg/repo1,github.com/myorg/repo2` +* Allowlist all repos under `myorg` on `github.com` + * `--repo-allowlist='github.com/myorg/*'` +* Allowlist all repos under `myorg` on `github.com`, excluding `myorg/untrusted-repo` + * `--repo-allowlist='github.com/myorg/*,!github.com/myorg/untrusted-repo'` +* Allowlist all repos in my GitHub Enterprise installation + * `--repo-allowlist='github.yourcompany.com/*'` +* Allowlist all repos under `myorg` project `myproject` on Azure DevOps + * `--repo-allowlist='myorg.visualstudio.com/myproject/*,dev.azure.com/myorg/myproject/*'` +* Allowlist all repositories + * `--repo-allowlist='*'` ### `--repo-config` + ```bash atlantis server --repo-config="path/to/repos.yaml" # or ATLANTIS_REPO_CONFIG="path/to/repos.yaml" ``` + Path to a YAML server-side repo config file. See [Server Side Repo Config](server-side-repo-config.md). ### `--repo-config-json` + ```bash atlantis server --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}' # or ATLANTIS_REPO_CONFIG_JSON='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}' ``` + Specify server-side repo config as a JSON string. Useful if you don't want to write a config file to disk. See [Server Side Repo Config](server-side-repo-config.md) for more details. ::: tip If specifying a [Workflow](custom-workflows.md#reference), [step](custom-workflows.md#step)'s can be specified as follows: + ```json { "repos": [], @@ -926,25 +1086,30 @@ This is useful when you have many projects and want to keep the pull request cle } } ``` + ::: ### `--restrict-file-list` + ```bash atlantis server --restrict-file-list # or (recommended) ATLANTIS_RESTRICT_FILE_LIST=true ``` + `--restrict-file-list` will block plan requests from projects outside the files modified in the pull request. This will not block plan requests with regex if using the `--enable-regexp-cmd` flag, in these cases commands like `atlantis plan -p .*` will still work if used. normal commands will stil be blocked if necessary. Defaults to `false`. ### `--silence-allowlist-errors` + ```bash atlantis server --silence-allowlist-errors # or ATLANTIS_SILENCE_ALLOWLIST_ERRORS=true ``` + Some users use the `--repo-allowlist` flag to control which repos Atlantis responds to. Normally, if Atlantis receives a pull request webhook from a repo not listed in the allowlist, it will comment back with an error. This flag disables that commenting. @@ -953,20 +1118,24 @@ This is useful when you have many projects and want to keep the pull request cle at an organization level rather than on each repo. ### `--silence-fork-pr-errors` + ```bash atlantis server --silence-fork-pr-errors # or ATLANTIS_SILENCE_FORK_PR_ERRORS=true ``` + Normally, if Atlantis receives a pull request webhook from a fork and --allow-fork-prs is not set, it will comment back with an error. This flag disables that commenting. ### `--silence-no-projects` + ```bash atlantis server --silence-no-projects # or ATLANTIS_SILENCE_NO_PROJECTS=true ``` + `--silence-no-projects` will tell Atlantis to ignore PRs if none of the modified files are part of a project defined in the `atlantis.yaml` file. This flag ensures an Atlantis server only responds to its explicitly declared projects. This has no effect if projects are undefined in the repo level `atlantis.yaml`. @@ -976,78 +1145,96 @@ This is useful when you have many projects and want to keep the pull request cle delegate work to each Atlantis server. Also useful when used with pre_workflow_hooks to dynamically generate an `atlantis.yaml` file. ### `--silence-vcs-status-no-plans` + ```bash atlantis server --silence-vcs-status-no-plans # or ATLANTIS_SILENCE_VCS_STATUS_NO_PLANS=true ``` + `--silence-vcs-status-no-plans` will tell Atlantis to ignore setting VCS status on plans if none of the modified files are part of a project defined in the `atlantis.yaml` file. ### `--silence-vcs-status-no-projects` + ```bash atlantis server --silence-vcs-status-no-projects # or ATLANTIS_SILENCE_VCS_STATUS_NO_PROJECTS=true ``` + `--silence-vcs-status-no-projects` will tell Atlantis to ignore setting VCS status on any command if none of the modified files are part of a project defined in the `atlantis.yaml` file. ### `--skip-clone-no-changes` + ```bash atlantis server --skip-clone-no-changes # or ATLANTIS_SKIP_CLONE_NO_CHANGES=true ``` + `--skip-clone-no-changes` will skip cloning the repo during autoplan if there are no changes to Terraform projects. This will only apply for GitHub and GitLab and only for repos that have `atlantis.yaml` file. Defaults to `false`. ### `--slack-token` + ```bash atlantis server --slack-token=token # or (recommended) ATLANTIS_SLACK_TOKEN='token' ``` + API token for Slack notifications. Slack is not fully supported. TODO: Slack docs. ### `--ssl-cert-file` + ```bash atlantis server --ssl-cert-file="/etc/ssl/certs/my-cert.crt" # or ATLANTIS_SSL_CERT_FILE="/etc/ssl/certs/my-cert.crt" ``` + File containing x509 Certificate used for serving HTTPS. If the cert is signed by a CA, the file should be the concatenation of the server's certificate, any intermediates, and the CA's certificate. ### `--ssl-key-file` + ```bash atlantis server --ssl-key-file="/etc/ssl/private/my-cert.key" # or ATLANTIS_SSL_KEY_FILE="/etc/ssl/private/my-cert.key" ``` + File containing x509 private key matching `--ssl-cert-file`. ### `--stats-namespace` + ```bash atlantis server --stats-namespace="myatlantis" # or ATLANTIS_STATS_NAMESPACE="myatlantis" ``` + Namespace for emitting stats/metrics. See [stats](stats.md) section. ### `--tf-download` + ```bash atlantis server --tf-download=false # or ATLANTIS_TF_DOWNLOAD=false ``` + Defaults to `true`. Allow Atlantis to list and download additional versions of Terraform. Setting this to `false` can be useful in an air-gapped environment where a download mirror is not available. ### `--tf-download-url` + ```bash atlantis server --tf-download-url="https://releases.company.com" # or ATLANTIS_TF_DOWNLOAD_URL="https://releases.company.com" ``` + An alternative URL to download Terraform versions if they are missing. Useful in an airgapped environment where releases.hashicorp.com is not available. Directory structure of the custom endpoint should match that of releases.hashicorp.com. @@ -1055,106 +1242,128 @@ Setting this to `false` can be useful in an air-gapped environment where a downl This has no impact if `--tf-download` is set to `false`. ### `--tfe-hostname` + ```bash atlantis server --tfe-hostname="my-terraform-enterprise.company.com" # or ATLANTIS_TFE_HOSTNAME="my-terraform-enterprise.company.com" ``` + Hostname of your Terraform Enterprise installation to be used in conjunction with `--tfe-token`. See [Terraform Cloud](terraform-cloud.md) for more details. If using Terraform Cloud (i.e. you don't have your own Terraform Enterprise installation) no need to set since it defaults to `app.terraform.io`. ### `--tfe-local-execution-mode` + ```bash atlantis server --tfe-local-execution-mode # or ATLANTIS_TFE_LOCAL_EXECUTION_MODE=true ``` + Enable if you're using local execution mode (instead of TFE/C's remote execution mode). See [Terraform Cloud](terraform-cloud.md) for more details. ### `--tfe-token` + ```bash atlantis server --tfe-token="xxx.atlasv1.yyy" # or (recommended) ATLANTIS_TFE_TOKEN='xxx.atlasv1.yyy' ``` + A token for Terraform Cloud/Terraform Enterprise integration. See [Terraform Cloud](terraform-cloud.md) for more details. ### `--use-tf-plugin-cache` + ```bash atlantis server --use-tf-plugin-cache=false # or ATLANTIS_USE_TF_PLUGIN_CACHE=false ``` + Set to false if you want to disable terraform plugin cache. This flag is useful when having multiple projects that need to run a plan and apply in the same PR to avoid the race condition of `plugin_cache_dir` concurrently, this is a terraform known issue, more info: -- [plugin_cache_dir concurrently discussion](https://github.com/hashicorp/terraform/issues/31964) -- [PR to improve the situation](https://github.com/hashicorp/terraform/pull/33479) +* [plugin_cache_dir concurrently discussion](https://github.com/hashicorp/terraform/issues/31964) +* [PR to improve the situation](https://github.com/hashicorp/terraform/pull/33479) The effect of the race condition is more evident when using parallel configuration to run plan and apply, by disabling the use of plugin cache will impact in the performance when starting a new plan or apply, but in large atlantis deployments with multiple projects and shared modules the use of `--parallel_plan` and `--parallel_apply` is mandatory for an efficient managment of the PRs. ### `--var-file-allowlist` + ```bash atlantis server --var-file-allowlist='/path/to/tfvars/dir' # or ATLANTIS_VAR_FILE_ALLOWLIST='/path/to/tfvars/dir' ``` + Comma-separated list of additional directory paths where [variable definition files](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files) can be read from. The paths in this argument should be absolute paths. Relative paths and globbing are currently not supported. If this argument is not provided, it defaults to Atlantis' data directory, determined by the `--data-dir` argument. ### `--vcs-status-name` + ```bash atlantis server --vcs-status-name="atlantis-dev" # or ATLANTIS_VCS_STATUS_NAME="atlantis-dev" ``` + Name used to identify Atlantis when updating a pull request status. Defaults to `atlantis`. This is useful when running multiple Atlantis servers against a single repository so you can give each Atlantis server its own unique name to prevent the statuses clashing. ### `--web-basic-auth` + ```bash atlantis server --web-basic-auth # or ATLANTIS_WEB_BASIC_AUTH=true ``` + Enable Basic Authentication on the Atlantis web service. ### `--web-password` + ```bash atlantis server --web-password="atlantis" # or ATLANTIS_WEB_PASSWORD="atlantis" ``` + Password used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. ### `--web-username` + ```bash atlantis server --web-username="atlantis" # or ATLANTIS_WEB_USERNAME="atlantis" ``` + Username used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`. ### `--websocket-check-origin` + ```bash atlantis server --websocket-check-origin # or ATLANTIS_WEBSOCKET_CHECK_ORIGIN=true ``` + Only allow websockets connection when they originate from the running Atlantis web server ### `--write-git-creds` + ```bash atlantis server --write-git-creds # or ATLANTIS_WRITE_GIT_CREDS=true ``` + Write out a .git-credentials file with the provider user and token to allow cloning private modules over HTTPS or SSH. See [here](https://git-scm.com/docs/git-credential-store) for more information. @@ -1171,4 +1380,3 @@ The effect of the race condition is more evident when using parallel configurati ::: warning SECURITY WARNING This does write secrets to disk and should only be enabled in a secure environment. ::: - diff --git a/runatlantis.io/docs/server-side-repo-config.md b/runatlantis.io/docs/server-side-repo-config.md index a3b03ba902..7fca97e901 100644 --- a/runatlantis.io/docs/server-side-repo-config.md +++ b/runatlantis.io/docs/server-side-repo-config.md @@ -5,8 +5,6 @@ A Server-Side Config file is used for more groups of server config that can't re One such usecase is to control per-repo behaviour and what users can do in repo-level `atlantis.yaml` files. -[[toc]] - ## Do I Need A Server-Side Config File? You do not need a server-side repo config file unless you want to customize diff --git a/runatlantis.io/docs/terraform-cloud.md b/runatlantis.io/docs/terraform-cloud.md index bab22a5db0..1d59ac7cd6 100644 --- a/runatlantis.io/docs/terraform-cloud.md +++ b/runatlantis.io/docs/terraform-cloud.md @@ -6,15 +6,17 @@ and Private Terraform Enterprise was renamed Terraform Enterprise. ::: Atlantis integrates seamlessly with Terraform Cloud and Terraform Enterprise, whether you're using: + * [Free Remote State Management](https://app.terraform.io) * Terraform Cloud Paid Tiers * A Private Installation of Terraform Enterprise Read the docs below :point_down: depending on your use-case. -[[toc]] ## Using Atlantis With Free Remote State Storage + To use Atlantis with Free Remote State Storage, you need to: + 1. Migrate your state to Terraform Cloud. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate) 1. Update any projects that are referencing the state you migrated to use the new location 1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token) @@ -24,6 +26,7 @@ That's it! Atlantis will run as normal and your state will be stored in Terrafor Cloud. ## Using Atlantis With Terraform Cloud Remote Operations or Terraform Enterprise + Atlantis integrates with the full version of Terraform Cloud and Terraform Enterprise via the [remote backend](https://developer.hashicorp.com/terraform/language/settings/backends/remote). @@ -31,7 +34,9 @@ Atlantis will run `terraform` commands as usual, however those commands will actually be executed *remotely* in Terraform Cloud or Terraform Enterprise. ### Why? + Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to features like: + * Real-time streaming output * Ability to cancel in-progress commands * Secret variables @@ -40,28 +45,34 @@ Using Atlantis with Terraform Cloud or Terraform Enterprise gives you access to **Without** having to change your pull request workflow. ### Getting Started + To use Atlantis with Terraform Cloud Remote Operations or Terraform Enterprise, you need to: + 1. Migrate your state to Terraform Cloud/Enterprise. See [Migrating State from Local Terraform](https://developer.hashicorp.com/terraform/cloud-docs/migrate) 1. Update any projects that are referencing the state you migrated to use the new location 1. [Generate a Terraform Cloud/Enterprise Token](#generating-a-terraform-cloud-enterprise-token) 1. [Pass the token to Atlantis](#passing-the-token-to-atlantis) ## Generating a Terraform Cloud/Enterprise Token + Atlantis needs a Terraform Cloud/Enterprise Token that it will use to access the API. Using a **Team Token is recommended**, however you can also use a User Token. ### Team Token + To generate a team token, click on **Settings** in the top bar, then **Teams** in the sidebar. Choose an existing team or create a new one. Enable the **Manage Workspaces** permission, then scroll down to **Team API Token**. ### User Token + To generate a user token, click on your avatar, then **User Settings**, then **Tokens** in the sidebar. Ensure the **Manage Workspaces** permission is enabled for this user's team. ## Passing The Token To Atlantis + The token can be passed to Atlantis via the `ATLANTIS_TFE_TOKEN` environment variable. You can also use the `--tfe-token` flag, however your token would then be easily @@ -88,12 +99,14 @@ Under the hood, Atlantis is generating a `~/.terraformrc` file. If you already had a `~/.terraformrc` file where Atlantis is running, then you'll need to manually add the credentials block to that file: + ``` ... credentials "app.terraform.io" { token = "xxxx" } ``` + instead of using the `ATLANTIS_TFE_TOKEN` environment variable, since Atlantis won't overwrite your `.terraformrc` file. ::: diff --git a/runatlantis.io/docs/using-atlantis.md b/runatlantis.io/docs/using-atlantis.md index acbe7e27e4..722e6502ef 100644 --- a/runatlantis.io/docs/using-atlantis.md +++ b/runatlantis.io/docs/using-atlantis.md @@ -5,6 +5,7 @@ Atlantis triggers commands via pull request comments. ::: tip You can use following executable names. + * `atlantis help` * `atlantis` is executable name. You can configure by [Executable Name](server-configuration.md#executable-name). * `run help` @@ -14,35 +15,46 @@ You can use following executable names. ::: Currently, Atlantis supports the following commands. -[[toc]] --- + ## atlantis help + ```bash atlantis help ``` + ### Explanation + View help --- + ## atlantis version + ```bash atlantis version ``` ### Explanation + Print the output of 'terraform version'. --- + ## atlantis plan + ```bash atlantis plan [options] -- [terraform plan flags] ``` + ### Explanation + Runs `terraform plan` on the pull request's branch. You may wish to re-run plan after Atlantis has already done so if you've changed some resources manually. ### Examples + ```bash # Runs plan for any projects that Atlantis thinks were modified. # If an `atlantis.yaml` file is specified, runs plan on the projects that @@ -60,8 +72,9 @@ atlantis plan -w staging ``` ### Options + * `-d directory` Which directory to run plan in relative to root of repo. Use `.` for root. - * Ex. `atlantis plan -d child/dir` + * Ex. `atlantis plan -d child/dir` * `-p project` Which project to run plan for. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w` because the project defines this already. * `-w workspace` Switch to this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces) before planning. Defaults to `default`. Ignore this if Terraform workspaces are unused. * `--verbose` Append Atlantis log to comment. @@ -74,30 +87,38 @@ A `atlantis plan` (without flags), like autoplans, discards all plans previously If `terraform plan` requires additional arguments, like `-target=resource` or `-var 'foo=bar'` or `-var-file myfile.tfvars` you can append them to the end of the comment after `--`, ex. + ``` atlantis plan -d dir -- -var foo='bar' ``` + If you always need to append a certain flag, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). ### Using the -destroy Flag #### Example + To perform a destructive plan that will destroy resources you can use the `-destroy` flag like this: ```bash atlantis plan -- -destroy atlantis plan -d dir -- -destroy ``` -::: warning NOTE + +::: warning NOTE The `-destroy` flag generates a destroy plan, If this plan is applied it can result in data loss or service disruptions. Ensure that you have thoroughly reviewed your Terraform configuration and intend to remove the specified resources before using this flag. ::: --- + ## atlantis apply + ```bash atlantis apply [options] -- [terraform apply flags] ``` + ### Explanation + Runs `terraform apply` for the plan that matches the directory/project/workspace. ::: tip @@ -106,8 +127,8 @@ This includes all projects that have been planned manually with `atlantis plan` For Atlantis commands to work, Atlantis needs to know the location where the plan file is. For that, you can use $PLANFILE which will contain the path of the plan file to be used in your custom steps. i.e `terraform plan -out $PLANFILE` ::: - ### Examples + ```bash # Runs apply for all unapplied plans from this pull request. atlantis apply @@ -123,6 +144,7 @@ atlantis apply -w staging ``` ### Options + * `-d directory` Apply the plan for this directory, relative to root of repo. Use `.` for root. * `-p project` Apply the plan for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml` file](repo-level-atlantis-yaml.md). Cannot be used at same time as `-d` or `-w`. * `-w workspace` Apply the plan for this [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. @@ -132,6 +154,7 @@ atlantis apply -w staging ### Additional Terraform flags Because Atlantis under the hood is running `terraform apply plan.tfplan`, any Terraform options that would change the `plan` are ignored, ex: + * `-target=resource` * `-var 'foo=bar'` * `-var-file=myfile.tfvars` @@ -140,17 +163,22 @@ They're ignored because they can't be specified for an already generated planfil If you would like to specify these flags, do it while running `atlantis plan`. --- + ## atlantis import + ```bash atlantis import [options] ADDRESS ID -- [terraform import flags] ``` + ### Explanation + Runs `terraform import` that matches the directory/project/workspace. This command discards the terraform plan result. After an import and before an apply, another `atlantis plan` must be run again. To allow the `import` command requires [--allow-commands](server-configuration.md#allow-commands) configuration. ### Examples + ```bash # Runs import atlantis import ADDRESS ID @@ -166,11 +194,13 @@ atlantis import -w staging ADDRESS ID ``` ::: tip + * If import for_each resources, it requires a single quoted address. * ex. `atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0` ::: ### Options + * `-d directory` Import a resource for this directory, relative to root of repo. Use `.` for root. * `-p project` Import a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`. * `-w workspace` Import a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. @@ -179,23 +209,30 @@ atlantis import -w staging ADDRESS ID If `terraform import` requires additional arguments, like `-var 'foo=bar'` or `-var-file myfile.tfvars` append them to the end of the comment after `--`, e.g. + ``` atlantis import -d dir 'aws_instance.example["foo"]' i-1234567890abcdef0 -- -var foo='bar' ``` + If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). --- + ## atlantis state rm + ```bash atlantis state [options] rm ADDRESS... -- [terraform state rm flags] ``` + ### Explanation + Runs `terraform state rm` that matches the directory/project/workspace. This command discards the terraform plan result. After run state rm and before an apply, another `atlantis plan` must be run again. To allow the `state` command requires [--allow-commands](server-configuration.md#allow-commands) configuration. ### Examples + ```bash # Runs state rm atlantis state rm ADDRESS1 ADDRESS2 @@ -211,11 +248,13 @@ atlantis state -w staging rm ADDRESS ``` ::: tip + * If run state rm to for_each resources, it requires a single quoted address. * ex. `atlantis state rm 'aws_instance.example["foo"]'` ::: ### Options + * `-d directory` Run state rm a resource for this directory, relative to root of repo. Use `.` for root. * `-p project` Run state rm a resource for this project. Refers to the name of the project configured in the repo's [`atlantis.yaml`](repo-level-atlantis-yaml.md) repo configuration file. This cannot be used at the same time as `-d` or `-w`. * `-w workspace` Run state rm a resource for a specific [Terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces). Ignore this if Terraform workspaces are unused. @@ -224,31 +263,40 @@ atlantis state -w staging rm ADDRESS If `terraform state rm` requires additional arguments, like `-lock=false'` append them to the end of the comment after `--`, e.g. + ``` atlantis state -d dir rm 'aws_instance.example["foo"]' -- -lock=false ``` + If a flag is needed to be always appended, see [Custom Workflow Use Cases](custom-workflows.md#adding-extra-arguments-to-terraform-commands). --- + ## atlantis unlock + ```bash atlantis unlock ``` ### Explanation + Removes all atlantis locks and discards all plans for this PR. To unlock a specific plan you can use the Atlantis UI. --- + ## atlantis approve_policies + ```bash atlantis approve_policies ``` ### Explanation + Approves all current policy checking failures for the PR. See also [policy checking](policy-checking.md). ### Options + * `--verbose` Append Atlantis log to comment. diff --git a/runatlantis.io/guide/testing-locally.md b/runatlantis.io/guide/testing-locally.md index feb2969e06..900f238e49 100644 --- a/runatlantis.io/guide/testing-locally.md +++ b/runatlantis.io/guide/testing-locally.md @@ -1,4 +1,5 @@ # Testing Locally + These instructions are for running Atlantis **locally on your own computer** so you can test it out against your own repositories before deciding whether to install it more permanently. @@ -8,20 +9,22 @@ If you want to set up a production-ready Atlantis installation, read [Deployment Steps: -[[toc]] - ## Install Terraform + `terraform` needs to be in the `$PATH` for Atlantis. Download from [Terraform](https://developer.hashicorp.com/terraform/downloads) + ``` unzip path/to/terraform_*.zip -d /usr/local/bin ``` ## Download Atlantis + Get the latest release from [GitHub](https://github.com/runatlantis/atlantis/releases) and unpackage it. ## Download Ngrok + Atlantis needs to be accessible somewhere that github.com/gitlab.com/bitbucket.org or your GitHub/GitLab Enterprise installation can reach. One way to accomplish this is with ngrok, a tool that forwards your local port to a random public hostname. @@ -29,17 +32,20 @@ public hostname. [Download](https://ngrok.com/download) ngrok and `unzip` it. Start `ngrok` on port `4141` and take note of the hostname it gives you: + ```bash ./ngrok http 4141 ``` In a new tab (where you'll soon start Atlantis) create an environment variable with ngrok's hostname: + ```bash URL="https://{YOUR_HOSTNAME}.ngrok.io" ``` ## Create a Webhook Secret + GitHub and GitLab use webhook secrets so clients can verify that the webhooks came from them. ::: warning @@ -49,14 +55,17 @@ to ensure the webhooks are coming from them. ::: Create a random string of any length (you can use [random.org](https://www.random.org/strings/)) and set an environment variable: + ``` SECRET="{YOUR_RANDOM_STRING}" ``` ## Add Webhook + Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo: ### GitHub or GitHub Enterprise Webhook +
Expand
    @@ -82,6 +91,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
### GitLab or GitLab Enterprise Webhook +
Expand
    @@ -103,6 +113,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
### Bitbucket Cloud (bitbucket.org) Webhook +
Expand
    @@ -124,6 +135,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
### Bitbucket Server (aka Stash) Webhook +
Expand
    @@ -141,6 +153,7 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
### Gitea Webhook +
Expand
    @@ -170,38 +183,45 @@ Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bi
- ## Create an access token for Atlantis + We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing, you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and set commit statuses. ### GitHub or GitHub Enterprise Access Token + - Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token) - create a token with **repo** scope - set the token as an environment variable + ``` TOKEN="{YOUR_TOKEN}" ``` ### GitLab or GitLab Enterprise Access Token + - follow [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token) - create a token with **api** scope - set the token as an environment variable + ``` TOKEN="{YOUR_TOKEN}" ``` ### Bitbucket Cloud (bitbucket.org) Access Token + - follow [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/) - Label the password "atlantis" - Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them - set the token as an environment variable + ``` TOKEN="{YOUR_TOKEN}" ``` ### Bitbucket Server (aka Stash) Access Token + - Click on your avatar in the top right and select **Manage account** - Click **HTTP access tokens** in the sidebar - Click **Create token** @@ -209,11 +229,13 @@ TOKEN="{YOUR_TOKEN}" - Give the token **Read** Project permissions and **Write** Pull request permissions - Choose an Expiry option **Do not expire** or **Expire automatically** - Click **Create** and set the token as an environment variable + ``` TOKEN="{YOUR_TOKEN}" ``` ### Gite Access Token + - Go to "Profile and Settings" > "Settings" in Gitea (top-right) - Go to "Applications" under "User Settings" in Gitea - Create a token under the "Manage Access Tokens" with the following permissions: @@ -222,6 +244,7 @@ TOKEN="{YOUR_TOKEN}" - Record the access token ## Start Atlantis + You're almost ready to start Atlantis, just set two more variables: ```bash @@ -232,9 +255,11 @@ REPO_ALLOWLIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO" # server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo # is under, **not the key** of the project. ``` + Now you can start Atlantis. The exact command differs depending on your Git host: ### GitHub Command + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -245,6 +270,7 @@ atlantis server \ ``` ### GitHub Enterprise Command + ```bash HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io atlantis server \ @@ -257,6 +283,7 @@ atlantis server \ ``` ### GitLab Command + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -267,6 +294,7 @@ atlantis server \ ``` ### GitLab Enterprise Command + ```bash HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io atlantis server \ @@ -279,6 +307,7 @@ atlantis server \ ``` ### Bitbucket Cloud (bitbucket.org) Command + ```bash atlantis server \ --atlantis-url="$URL" \ @@ -288,6 +317,7 @@ atlantis server \ ``` ### Bitbucket Server (aka Stash) Command + ```bash BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990 atlantis server \ @@ -331,16 +361,20 @@ atlantis server \ ``` ## Create a pull request + Create a pull request so you can test Atlantis. ::: tip You could add a null resource as a test: + ```hcl resource "null_resource" "example" {} ``` + Or just modify the whitespace in a file. ::: ### Autoplan + You should see Atlantis logging about receiving the webhook and you should see the output of `terraform plan` on your repo. Atlantis tries to figure out the directory to plan in based on the files modified. @@ -348,28 +382,34 @@ If you need to customize the directories that Atlantis runs in or the commands i or `.tfvars` files, see [atlantis.yaml Reference](../docs/repo-level-atlantis-yaml.md#reference). ### Manual Plan + To manually `plan` in a specific directory or workspace, comment on the pull request using the `-d` or `-w` flags: + ``` atlantis plan -d mydir atlantis plan -w staging ``` To add additional arguments to the underlying `terraform plan` you can use: + ``` atlantis plan -- -target=resource -var 'foo=bar' ``` ### Apply + If you'd like to `apply`, type a comment: `atlantis apply`. You can use the `-d` or `-w` flags to point Atlantis at a specific plan. Otherwise it tries to apply the plan for the root directory. ## Real-time logs + The [real-time terraform output](../docs/streaming-logs.md) for your command can be found by clicking into the status check for a given project in a PR which links to the log-streaming UI. This is a terminal UI where you can view your commands executing in real-time. ## Next Steps + * If things are working as expected you can `Ctrl-C` the `atlantis server` command and the `ngrok` command. -* Hopefully Atlantis is working with your repo and you're ready to move on to a [production-ready deployment](../docs/deployment.md). -* If it's not working as expected, you may need to customize how Atlantis runs with an `atlantis.yaml` file. +- Hopefully Atlantis is working with your repo and you're ready to move on to a [production-ready deployment](../docs/deployment.md). +- If it's not working as expected, you may need to customize how Atlantis runs with an `atlantis.yaml` file. See [atlantis.yaml use cases](../docs/repo-level-atlantis-yaml.md#use-cases). -* Check out our [full documentation](../docs.md) for more details. +- Check out our [full documentation](../docs.md) for more details.