From d3bc4e3af71ffa93921ffc0dcac86890639e820e Mon Sep 17 00:00:00 2001
From: Brett Galkowski <bgalkows@google.com>
Date: Thu, 14 Sep 2023 16:38:13 -0700
Subject: [PATCH] Adding documentation steps for custom policy tools

---
 runatlantis.io/docs/custom-policy-checks.md   | 45 +++++++++++++++++++
 .../docs/server-side-repo-config.md           |  3 ++
 2 files changed, 48 insertions(+)
 create mode 100644 runatlantis.io/docs/custom-policy-checks.md

diff --git a/runatlantis.io/docs/custom-policy-checks.md b/runatlantis.io/docs/custom-policy-checks.md
new file mode 100644
index 0000000000..769558910d
--- /dev/null
+++ b/runatlantis.io/docs/custom-policy-checks.md
@@ -0,0 +1,45 @@
+# Custom Policy Checks
+If you want to run custom policy tools or scripts instead of the built-in Conftest integration, you can do so by setting the `custom_policy_check` option and running it in a custom workflow.  Note: custom policy tool output is simply parsed for "fail" substrings to determine if the policy set passed. 
+
+This option can be configured either at the server-level in a [repos.yaml config file](server-configuration.md) or at the repo-level in an [atlantis.yaml file.](repo-level-atlantis-yaml.md). 
+
+## Server-side config example
+Set the `policy_check` and `custom_policy_check` options to true, and run the custom tool in the policy check steps as seen below.  No
+
+```yaml
+repos:
+  - id: /.*/
+    branch: /^main$/
+    apply_requirements: [mergeable, undiverged, approved]
+    policy_check: true
+    custom_policy_check: true
+    workflow: custom
+workflows:
+  custom:
+    policy_check:
+      steps:
+        - show
+        - run: cnspec scan terraform plan $SHOWFILE --policy-bundle example-cnspec-policies.mql.yaml 
+policies:
+  owners:
+    users:
+      - example_ghuser
+  policy_sets:
+    - name: example-set
+      path: example-cnspec-policies.mql.yaml 
+      source: local
+```
+
+
+## Repo-level atlantis.yaml example
+First, you will need to ensure `custom_policy_check` is within the `allowed_overrides` field of the server-side config.  Next, just set the custom option to true on the specific project you want as shown in the example `atlantis.yaml` below:
+
+```yaml
+version: 3
+projects:
+  - name: example
+    dir: ./example
+    custom_policy_check: true
+    autoplan:
+      when_modified: ["*.tf"]
+```
\ No newline at end of file
diff --git a/runatlantis.io/docs/server-side-repo-config.md b/runatlantis.io/docs/server-side-repo-config.md
index e8a38d965a..01d8a175aa 100644
--- a/runatlantis.io/docs/server-side-repo-config.md
+++ b/runatlantis.io/docs/server-side-repo-config.md
@@ -344,6 +344,9 @@ unless you've created your own server-side workflow with that key (overriding it
 See [Custom Workflows](custom-workflows.html) 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`.