IaC Governance Setup
Connect GitHub so ZopNight can check every Terraform or OpenTofu pull request against your policies. Lists the exact GitHub access to grant, what your CI sends to ZopNight, and what your CI must already have.
IaC Governance checks each Terraform or OpenTofu pull request against the policies you attach
in ZopNight. Your own CI runs plan and sends the plan to ZopNight. ZopNight replies with a pass or
fail and a comment on the pull request. You can make that result a required check, so a failing
change can't be merged.
Before you start
| Need | Detail |
|---|---|
| A GitHub account on github.com | GitHub Enterprise Server and GitLab are not supported. |
| Someone who can install GitHub Apps | An organisation owner, or a repo admin if your org allows it. |
| A ZopNight Admin | Only Admins can connect GitHub. Editors and Admins attach policies. |
| Terraform or OpenTofu at the repo root | The workflow runs init and plan from the root folder. |
| Cloud and state credentials in your CI | Your runners must already be able to run terraform plan. |
| Outbound HTTPS from your runners | To the ZopNight API (ZOPNIGHT_API_URL) and to GitHub for public actions. |
Access to grant
Connect with the ZopNight GitHub App. It asks for these repository permissions, and only on the repos you pick during install. Each one is the level GitHub lists for the API call ZopNight makes, in Permissions required for GitHub Apps.
| GitHub App permission | Access | Why ZopNight needs it |
|---|---|---|
| Metadata | Read | Required for every app. Reads the default branch. |
| Contents | Read and write | Finds the workflow file; creates the branch and the file. |
| Workflows | Read and write | Needed to add a file under .github/workflows/. |
| Secrets | Read and write | Stores the scan token as the repo secret ZOPNIGHT_TOKEN. |
| Variables | Read and write | Sets the repo variables ZOPNIGHT_API_URL and ZOPNIGHT_ORG. |
| Pull requests | Read and write | Opens the setup pull request and checks its status. |
GitHub needs Contents and Workflows together to write a workflow file. See Create or update file contents. The app subscribes to no webhook events and asks for no organisation or account permissions.
What the workflow in your repo does
The setup pull request adds .github/workflows/zopnight-governance.yml. It runs on pull requests,
on pushes, and when started by hand. It has two jobs:
| Job | Runs on | What it sends |
|---|---|---|
validate | Every pull request | The trimmed plan, to get a pass or fail and post a comment |
scan | Pushes to the default branch, and manual runs | The full state, to match your code to discovered resources |
Its job token asks for only:
permissions:
contents: read # check out the code
pull-requests: write # post and update the verdict commentAny permission not listed is
set to none.
It reads one secret and up to three variables:
| Name | Type | Value |
|---|---|---|
ZOPNIGHT_TOKEN | Secret | A scan token that can only run validations and read policies. |
ZOPNIGHT_API_URL | Variable | The ZopNight API address. |
ZOPNIGHT_ORG | Variable | Your ZopNight organisation ID. |
ZOPNIGHT_IAC_TOOL | Variable, optional | Set it to tofu to use OpenTofu. ZopNight does not set it. |
Set it up
Install the GitHub App
In ZopNight, open Settings → Integrations → GitHub and click Connect. Choose Install GitHub App. On GitHub, pick the organisation and the repos to allow, then approve. You return to ZopNight and see GitHub connected.
Attach a policy
Open Governance → IaC Validations and click Attach policy. Pick a rule and set it up. Set Enforcement to Mandatory if a violation must block the merge; Advisory only warns. In Scope, choose the connected account and the repos. Click Create policy.
Merge the setup pull request
ZopNight opens a setup pull request from the branch
zopnight/governancein each repo. The toast has an Open PR button. Review it and merge it into your default branch.Make the check required (recommended)
In the repo on GitHub, open Settings → Rulesets (or Settings → Branches → Add classic branch protection rule). Turn on Require status checks to pass and add validate. It shows as ZopNight IaC Governance / validate. The check fails only on a Mandatory policy violation. GitHub only offers a check that has completed successfully in the repo in the past seven days. See Creating rulesets for a repository.
Each repo card on the Repositories tab of IaC Validations shows where setup stands:
| Badge | Meaning |
|---|---|
| Merge setup PR | The setup pull request is open. Merge it. |
| CI active | The workflow is on the default branch and its token is valid. |
| CI token missing | The token was revoked. Attach a policy again to issue a new one. |
| CI not wired | Not set up yet, or GitHub refused access. Check the app covers this repo. |
Disconnect and remove access
Settings → Integrations → GitHub → Disconnect removes the connection from ZopNight and asks GitHub to uninstall the app. That uninstall is best effort: if GitHub refuses it, the connection is still removed. Check the app is gone in GitHub: for an organisation, Settings → Third-party Access → GitHub Apps; for a personal account, Settings → Applications → Installed GitHub Apps.
Disconnecting does not change your repos. To remove IaC Governance fully, also delete these from each repo:
- the file
.github/workflows/zopnight-governance.yml - the secret
ZOPNIGHT_TOKEN - the variables
ZOPNIGHT_API_URLandZOPNIGHT_ORG - the branch
zopnight/governance, if it is still there - the required validate check, if you added one
Troubleshooting
| Problem | Cause and fix |
|---|---|
| Pull requests from forks fail the check | Forks get no secrets. Use branches in the same repo. |
terraform init fails in the workflow | The runner has no cloud or state credentials. Add them as for your other Terraform workflows. |
| The check never reaches ZopNight | Runners can't reach ZOPNIGHT_API_URL. Allow outbound HTTPS to it. |
| A repo is missing from the Scope list | The app is not installed on that repo. Add it on the app's Configure page in GitHub. |