diff --git a/runatlantis.io/.vitepress/sidebars.ts b/runatlantis.io/.vitepress/sidebars.ts index 37e1c7c788..1afacb11c2 100644 --- a/runatlantis.io/.vitepress/sidebars.ts +++ b/runatlantis.io/.vitepress/sidebars.ts @@ -31,22 +31,21 @@ const en = [ collapsed: true, items: [ { text: "Overview", link: "/docs/configuring-atlantis" }, - "/docs/configuring-atlantis", - "/docs/server-configuration", - "/docs/server-side-repo-config", - "/docs/pre-workflow-hooks", - "/docs/post-workflow-hooks", - "/docs/policy-checking", - "/docs/custom-workflows", - "/docs/repo-level-atlantis-yaml", - "/docs/upgrading-atlantis-yaml", - "/docs/command-requirements", - "/docs/checkout-strategy", - "/docs/terraform-versions", - "/docs/terraform-cloud", - "/docs/using-slack-hooks", - "/docs/stats", - "/docs/faq", + { text: "Server Configuration", link: "/docs/server-configuration" }, + { text: "Server Side Repo Config", link: "/docs/server-side-repo-config" }, + { text: "Pre Workflow Hooks", link: "/docs/pre-workflow-hooks" }, + { text: "Post Workflow Hooks", link: "/docs/post-workflow-hooks" }, + { text: "Conftest Policy Checking", link: "/docs/policy-checking" }, + { text: "Custom Workflows", link: "/docs/custom-workflows" }, + { text: "Repo Level atlantis.yaml", link: "/docs/repo-level-atlantis-yaml" }, + { text: "Upgrading atlantis.yaml", link: "/docs/upgrading-atlantis-yaml" }, + { text: "Command Requirements", link: "/docs/command-requirements" }, + { text: "Checkout Strategy", link: "/docs/checkout-strategy" }, + { text: "Terraform Versions", link: "/docs/terraform-versions" }, + { text: "Terraform Cloud", link: "/docs/terraform-cloud" }, + { text: "Using Slack Hooks", link: "/docs/using-slack-hooks" }, + { text: "Stats", link: "/docs/stats" }, + { text: "FAQ", link: "/docs/faq" }, ] }, { @@ -54,35 +53,29 @@ const en = [ collapsed: true, items: [ { text: "Overview", link: "/docs/using-atlantis" }, - "/docs/api-endpoints", + { text: "API endpoints", link: "/docs/api-endpoints" }, ] }, { text: 'How Atlantis Works', collapsed: true, items: [ - { - text: 'Overview', - link: '/docs/how-atlantis-works', - }, - '/docs/locking', - '/docs/autoplanning', - '/docs/automerging', - '/docs/security', + { text: 'Overview', link: '/docs/how-atlantis-works', }, + { text: 'Locking', link: '/docs/locking', }, + { text: 'Autoplanning', link: '/docs/autoplanning', }, + { text: 'Automerging', link: '/docs/automerging', }, + { text: 'Security', link: '/docs/security', }, ] }, { text: 'Real-time Terraform Logs', - collapsed: true, - items: [ - '/docs/streaming-logs', - ] + link: '/docs/streaming-logs', }, { text: 'Troubleshooting', collapsed: true, items: [ - '/docs/troubleshooting', + { text: 'HTTPS, SSL, TLS', 'link': '/docs/troubleshooting-https', }, ] }, ], @@ -95,13 +88,13 @@ const en = [ { text: 'Implementation Details', items: [ - {text: "Events Controller", link: "/contributing/events-controller"}, + { text: "Events Controller", link: "/contributing/events-controller" }, ] }, - {text: "Glossary", link: "/contributing/glossary"}, + { text: "Glossary", link: "/contributing/glossary" }, ] } -]; +] -export { en }; +export { en } diff --git a/runatlantis.io/docs.md b/runatlantis.io/docs.md index b843552cba..8a013c795e 100644 --- a/runatlantis.io/docs.md +++ b/runatlantis.io/docs.md @@ -8,6 +8,7 @@ where you can try our [Test Drive](./guide/test-drive.md) or [Run Atlantis Local ::: ### Next Steps + * [Installing Atlantis](./docs/installation-guide.md)  –  Get Atlantis up and running * [Configuring Atlantis](./docs/configuring-atlantis.md)  –  Configure how Atlantis works for your specific use-cases * [Using Atlantis](./docs/using-atlantis.md)  –  How do you use Atlantis? diff --git a/runatlantis.io/docs/pre-workflow-hooks.md b/runatlantis.io/docs/pre-workflow-hooks.md index 2085953d77..edcd4a0e83 100644 --- a/runatlantis.io/docs/pre-workflow-hooks.md +++ b/runatlantis.io/docs/pre-workflow-hooks.md @@ -21,7 +21,7 @@ By default, `pre-workflow-hooks` do not prevent Atlantis from executing its workflows(`plan`, `apply`) even if a `run` command exits with an error. This behavior can be changed by setting the [fail-on-pre-workflow-hook-error](server-configuration.md#fail-on-pre-workflow-hook-error) flag in the Atlantis server configuration. -::: +::: ## Atlantis Command Targetting @@ -98,6 +98,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`. @@ -109,7 +110,7 @@ command](custom-workflows.md#custom-run-command). * `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`. - * `DIR` - The absolute path to the root of the cloned repository. + * `DIR` - The absolute path to the root of the cloned repository. * `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`. diff --git a/runatlantis.io/docs/server-side-repo-config.md b/runatlantis.io/docs/server-side-repo-config.md index 55b0346747..a3b03ba902 100644 --- a/runatlantis.io/docs/server-side-repo-config.md +++ b/runatlantis.io/docs/server-side-repo-config.md @@ -1,4 +1,5 @@ -# Server Side Config +# Server Side Repo Config + A Server-Side Config file is used for more groups of server config that can't reasonably be expressed through flags. One such usecase is to control per-repo behaviour @@ -7,12 +8,14 @@ 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 some aspect of Atlantis on a per-repo basis. Read through the [use-cases](#use-cases) to determine if you need it. ## Enabling Server Side Config + To use server side repo config create a config file, ex. `repos.yaml`, and pass it to the `atlantis server` command via the `--repo-config` flag, ex. `--repo-config=path/to/repos.yaml`. @@ -20,8 +23,9 @@ If you don't wish to write a config file to disk, you can use the `--repo-config-json` flag or `ATLANTIS_REPO_CONFIG_JSON` environment variable to specify your config as JSON. See [--repo-config-json](server-configuration.md#repo-config-json) for an example. - + ## Example Server Side Repo + ```yaml # repos lists the config for specific repos. repos: @@ -56,7 +60,7 @@ repos: # its atlantis.yaml file. allowed_overrides: [apply_requirements, workflow, delete_source_branch_on_merge, repo_locking, custom_policy_check] - # allowed_workflows specifies which workflows the repos that match + # allowed_workflows specifies which workflows the repos that match # are allowed to select. allowed_workflows: [custom] @@ -78,11 +82,11 @@ repos: custom_policy_check: false # pre_workflow_hooks defines arbitrary list of scripts to execute before workflow execution. - pre_workflow_hooks: + pre_workflow_hooks: - run: my-pre-workflow-hook-command arg1 - + # post_workflow_hooks defines arbitrary list of scripts to execute after workflow execution. - post_workflow_hooks: + post_workflow_hooks: - run: my-post-workflow-hook-command arg1 # policy_check defines if policy checking should be enable on this repository. @@ -112,13 +116,16 @@ workflows: ``` ## Use Cases + Here are some of the reasons you might want to use a repo config. ### Requiring PR Is Approved Before an applicable subcommand + If you want to require that all (or specific) repos must have pull requests approved before Atlantis will allow running `apply` or `import`, use the `plan_requirements`, `apply_requirements` or `import_requirements` keys. For all repos: + ```yaml # repos.yaml repos: @@ -129,6 +136,7 @@ repos: ``` For a specific repo: + ```yaml # repos.yaml repos: @@ -141,10 +149,12 @@ repos: See [Command Requirements](command-requirements.md) for more details. ### Requiring PR Is "Mergeable" Before Apply or Import + If you want to require that all (or specific) repos must have pull requests in a mergeable state before Atlantis will allow running `apply` or `import`, use the `plan_requirements`, `apply_requirements` or `import_requirements` keys. For all repos: + ```yaml # repos.yaml repos: @@ -155,6 +165,7 @@ repos: ``` For a specific repo: + ```yaml # repos.yaml repos: @@ -167,10 +178,12 @@ repos: See [Command Requirements](command-requirements.md) for more details. ### Repos Can Set Their Own Apply an applicable subcommand + If you want all (or specific) repos to be able to override the default apply requirements, use the `allowed_overrides` key. To allow all repos to override the default: + ```yaml # repos.yaml repos: @@ -183,7 +196,9 @@ repos: # But all repos can set their own using atlantis.yaml allowed_overrides: [plan_requirements, apply_requirements, import_requirements] ``` + To allow only a specific repo to override the default: + ```yaml # repos.yaml repos: @@ -200,6 +215,7 @@ repos: Then each allowed repo can have an `atlantis.yaml` file that sets `plan_requirements`, `apply_requirements` or `import_requirements` to an empty array (disabling the requirement). + ```yaml # atlantis.yaml in the repo root or set repo_config_file in repos.yaml version: 3 @@ -211,6 +227,7 @@ projects: ``` ### Running Scripts Before Atlantis Workflows + If you want to run scripts that would execute before Atlantis can run default or custom workflows, you can create a `pre-workflow-hooks`: @@ -222,10 +239,12 @@ repos: - run: | my bash script inline ``` + See [Pre Workflow Hooks](pre-workflow-hooks.md) for more details on writing pre workflow hooks. ### Running Scripts After Atlantis Workflows + If you want to run scripts that would execute after Atlantis runs default or custom workflows, you can create a `post-workflow-hooks`: @@ -237,15 +256,18 @@ repos: - run: | my bash script inline ``` + See [Post Workflow Hooks](post-workflow-hooks.md) for more details on writing post workflow hooks. ### Change The Default Atlantis Workflow + If you want to change the default commands that Atlantis runs during `plan` and `apply` phases, you can create a new `workflow`. If you want to use that workflow by default for all repos, use the workflow key `default`: + ```yaml # repos.yaml # NOTE: the repos key is not required. @@ -265,6 +287,7 @@ See [Custom Workflows](custom-workflows.md) for more details on writing custom workflows. ### Allow Repos To Choose A Server-Side Workflow + If you want repos to be able to choose their own workflows that are defined in the server-side repo config, you need to create the workflows server-side and then allow each repo to override the `workflow` key: @@ -295,7 +318,8 @@ workflows: steps: - run: another custom command ``` -Or, if you want to restrict what workflows each repo has access to, use the `allowed_workflows` + +Or, if you want to restrict what workflows each repo has access to, use the `allowed_workflows` key: ```yaml @@ -349,9 +373,11 @@ See [Custom Workflows](custom-workflows.md) for more details on writing custom workflows. ### Allow Using Custom Policy Tools + Conftest is the standard policy check application integrated with Atlantis, but custom tools can still be run in custom workflows when the `custom_policy_check` option is set. See the [Custom Policy Checks page](custom-policy-checks.md) for detailed examples. ### Allow Repos To Define Their Own Workflows + If you want repos to be able to define their own workflows you need to allow them to override the `workflow` key and set `allow_custom_workflows` to `true`. @@ -375,6 +401,7 @@ repos: ``` Then each allowed repo can define and use a custom workflow in their `atlantis.yaml` files: + ```yaml # atlantis.yaml version: 3 @@ -396,6 +423,7 @@ See [Custom Workflows](custom-workflows.md) for more details on writing custom workflows. ### Multiple Atlantis Servers Handle The Same Repository + Running multiple Atlantis servers to handle the same repository can be done to separate permissions for each Atlantis server. In this case, a different [atlantis.yaml](repo-level-atlantis-yaml.md) repository config file can be used by using different `repos.yaml` files. @@ -438,6 +466,7 @@ Now, 2 webhook URLs can be setup for the repository, which send events to `produ Each servers handle different repository config files. :::tip Notes + * If `no projects` comments are annoying, set [--silence-no-projects](server-configuration.md#silence-no-projects). * The command trigger executable name can be reconfigured from `atlantis` to something else by setting [Executable Name](server-configuration.md#executable-name). * When using different atlantis server vcs users such as `@atlantis-staging`, the comment `@atlantis-staging plan` can be used instead `atlantis plan` to call `staging-server` only. @@ -446,6 +475,7 @@ Each servers handle different repository config files. ## Reference ### Top-Level Keys + | Key | Type | Default | Required | Description | |-----------|-------------------------------------------------------|-----------|----------|---------------------------------------------------------------------------------------| | repos | array[[Repo](#repo)] | see below | no | List of repos to apply settings to. | @@ -453,10 +483,12 @@ Each servers handle different repository config files. | policies | Policies. | none | no | List of policy sets to run and associated metadata | | metrics | Metrics. | none | no | Map of metric configuration | - ::: tip A Note On Defaults + #### `repos` + `repos` always contains a first element with the Atlantis default config: + ```yaml repos: - id: /.*/ @@ -470,7 +502,9 @@ repos: ``` #### `workflows` + `workflows` always contains the Atlantis default workflow under the key `default`: + ```yaml workflows: default: @@ -485,6 +519,7 @@ If you set a workflow with the key `default`, it will override this. ::: ### Repo + | Key | Type | Default | Required | Description | |-------------------------------|--------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | string | none | yes | Value can be a regular expression when specified as /<regex>/ or an exact string match. Repo IDs are of the form `{vcs hostname}/{org}/{name}`, ex. `github.com/owner/repo`. Hostname is specified without scheme or port. For Bitbucket Server, {org} is the **name** of the project, not the key. | @@ -504,9 +539,11 @@ If you set a workflow with the key `default`, it will override this. | autodiscover | AutoDiscover | none | no | Auto discover settings for this repo | :::tip Notes + * If multiple repos match, the last match will apply. * If a key isn't defined, it won't override a key that matched from above. For example, given a repo ID `github.com/owner/repo` and a config: + ```yaml repos: - id: /.*/ @@ -517,12 +554,14 @@ If you set a workflow with the key `default`, it will override this. ``` The final config will look like: + ```yaml apply_requirements: [] workflow: default allowed_overrides: [] allow_custom_workflows: true ``` + Where * `apply_requirements` is set from the `id: github.com/owner/repo` config because it overrides the previous matching config from `id: /.*/`. @@ -544,6 +583,7 @@ If you set a workflow with the key `default`, it will override this. | policy_sets | []PolicySet | none | yes | set of policies to run on a plan output | ### Owners + | Key | Type | Default | Required | Description | |-------------|-------------------|---------|------------|---------------------------------------------------------| | users | []string | none | no | list of github users that can approve failing policies | @@ -557,7 +597,6 @@ If you set a workflow with the key `default`, it will override this. | path | string | none | yes | path to the rego policies directory | | source | string | none | yes | only `local` is supported at this time | - ### Metrics | Key | Type | Default | Required | Description | diff --git a/runatlantis.io/guide.md b/runatlantis.io/guide.md index 2d14a28c0a..9d71a3acf1 100644 --- a/runatlantis.io/guide.md +++ b/runatlantis.io/guide.md @@ -1,6 +1,7 @@ # Introduction ## Getting Started + * If you'd like to just test out running Atlantis on an **example repo** check out the [Test Drive](./guide/test-drive.md). * If you'd like to test out running Atlantis on **your repos** then read [Testing Locally](./guide/testing-locally.md). * If you're ready to properly install Atlantis on real infrastructure then head over to the [Installation Guide](./docs/installation-guide.md). @@ -10,6 +11,7 @@ Go here: [www.runatlantis.io/docs](./docs.md) ::: ## Overview – What Is Atlantis? + Atlantis is an application for automating Terraform via pull requests. It is deployed as a standalone application into your infrastructure. No third-party has access to your credentials. @@ -21,14 +23,18 @@ When you want to apply, comment `atlantis apply` on the pull request and Atlanti will run `terraform apply` and comment back with the output. ## Watch + Check out the video below to see it in action: [![Atlantis Walkthrough](./guide/images/atlantis-walkthrough-icon.png)](https://www.youtube.com/watch?v=TmIPWda0IKg) ## Why would you run Atlantis? + ### Increased visibility + When everyone is executing Terraform on their own computers, it's hard to know the current state of your infrastructure: + * Is what's in `main` branch deployed? * Did someone forget to create a pull request for that latest change? * What was the output from that last `terraform apply`? @@ -37,6 +43,7 @@ With Atlantis, everything is visible on the pull request. You can view the histo of everything that was done to your infrastructure. ### Enable collaboration with everyone + You probably don't want to distribute Terraform credentials to everyone in your engineering organization, but now anyone can open up a Terraform pull request. @@ -44,10 +51,12 @@ You can require approval before the pull request is applied so nothing happens accidentally. ### Review Terraform pull requests better + You can't fully review a Terraform change without seeing the output of `terraform plan`. Now that output is added to the pull request automatically. ### Standardize your workflows + Atlantis locks a directory/workspace until the pull request is merged or the lock is manually deleted. This ensures that changes are applied in the order expected. @@ -55,6 +64,7 @@ The exact commands that Atlantis runs are configurable. You can run custom scrip to construct your ideal workflow. ## Next Steps + * If you'd like to just test out running Atlantis on an **example repo** check out the [Test Drive](./guide/test-drive.md). * If you'd like to test out running Atlantis on **your repos** then read [Testing Locally](./guide/testing-locally.md). * If you're ready to properly install Atlantis on real infrastructure then head over to the [Installation Guide](./docs/installation-guide.md).