Update policies documentation for clarity and accuracy#3093
Update policies documentation for clarity and accuracy#3093octo-ryanhall wants to merge 6 commits intomainfrom
Conversation
octo-ryanhall
commented
Apr 10, 2026
octo-ryanhall
commented
- Revised the overview of policies to emphasize automatic enforcement of deployment standards.
- Clarified the input schema for policies, detailing available fields and their usage.
- Enhanced troubleshooting section to provide clearer guidance on diagnosing common policy evaluation issues.
- Updated examples and best practices for writing effective Rego conditions in policies.
- Adjusted publication and activation instructions for policies to ensure proper usage.
- Revised the overview of policies to emphasize automatic enforcement of deployment standards. - Clarified the input schema for policies, detailing available fields and their usage. - Enhanced troubleshooting section to provide clearer guidance on diagnosing common policy evaluation issues. - Updated examples and best practices for writing effective Rego conditions in policies. - Adjusted publication and activation instructions for policies to ensure proper usage.
|
|
…nd descriptions for clarity
…formatting, and enhance hints
shaun-od
left a comment
shaun-od
left a comment
There was a problem hiding this comment.
Ok looks good, I have not called out all the changes needed for certain suggestions like the code language or adding/changing the name of the Required Column in the example tables.
| Once you've confirmed the policy is working as expected, switch to `"action": "block"`. | ||
|
|
||
| Consider a policy that will block the execution of deployments and runbook runs. By default, that policy applies to all deployments and runbook runs. | ||
| ```rego |
There was a problem hiding this comment.
I think we use ruby as the language from memory as we don't have sytanx highlighting for rego
|
|
||
| ## Guard against conditional fields | ||
|
|
||
| Three input fields are not always present in the input object: `Tenant`, `Release`, and `Runbook`. Referencing them without checking for their existence first will cause a policy evaluation error. |
There was a problem hiding this comment.
We should add a link to the schema here so we don't have to keep updating this with optional properties.
Something like changing the below might be better.
Not all input fields are always present. For example, in the input object: `Tenant`, `Release`, and `Runbook` are optional and only provided when they are available. Referencing them without checking for their existence first will cause a policy evaluation error.
See [Schema for policies](its url) for the full list of available fields.
| ### Scope policy to a space or many spaces | ||
| **Scope** (apply to the environments where manual intervention is required): | ||
|
|
||
| ```ruby |
There was a problem hiding this comment.
Ok this should be ruby again so we can get some syntax highlighting
|
|
||
| ```json | ||
| input.Environment.Name = "Development" | ||
| ```rego |
|
|
||
| 1. **Check the scope Rego.** The scope determines which executions the policy evaluates. Open the policy editor and review your scope Rego. Use the verbose task log on a deployment you expect to be in scope to see what input fields were passed, and check whether your scope conditions would match. | ||
|
|
||
| 1. **Check the package name.** The package name in your scope and conditions Rego must exactly match your policy's slug. A mismatch will prevent the policy from evaluating. The slug is shown on the edit policy page. |
There was a problem hiding this comment.
If you don't have the package name correct then linting will fail so this line is not really valid, so I think we can remove it.
|
|
||
| #### Steps | ||
|
|
||
| | Property | Type | Required | Description | |
There was a problem hiding this comment.
Should Required column be Always present
| | Id | string | Yes | The unique identifier for the package reference | | ||
| | Name | string | Yes | The name of the package | | ||
| | Version | string | No | The resolved package version | | ||
| | GitRef | string | No | The Git reference the package was built from | |
There was a problem hiding this comment.
We should make a note that the GitRef comes from any linked Build Information
| | Enabled | boolean | Yes | Whether the step is enabled in the process | | ||
| | IsRequired | boolean | Yes | Whether the step has been marked as required | | ||
| | Source | object | Yes | Where the step comes from. See the Source object below | | ||
| | Packages | array | No | Packages referenced by this step | |
There was a problem hiding this comment.
It should be notes Packages are not available for runbook runs
| | Id | string | Yes | The unique identifier for the runbook | | ||
| | Name | string | Yes | The display name of the runbook | | ||
| | Snapshot | string | Yes | The snapshot name used for this run | | ||
| | GitRef | string | No | The Git reference the runbook was published from | |
There was a problem hiding this comment.
We should note that GitRef is only available for VCS controlled runbooks
| | Id | string | Yes | The unique identifier for the release | | ||
| | Name | string | Yes | The release name | | ||
| | Version | string | Yes | The release version string | | ||
| | GitRef | string | No | The Git reference the release was created from | |
There was a problem hiding this comment.
We should note that GitRef is only available for VCS projects
4 participants
