»Publishing Policy Libraries
A policy library is a collection of Sentinel policies and policy modules on the Terraform Registry. Sentinel is an embedded policy-as-code framework that lets you make detailed, logic-based policy decisions.
You can build and maintain policy libraries on GitHub and then publish them to the Terraform Registry. This page explains how to format and publish policy libraries as well as how to release new versions.
Review the following before publishing a new policy library or policy library version.
The Github repository for your policy library must adhere to the following conventions:
- The repository must be public.
- The repository name must follow the convention
policy-library-<NAME>, where the
<NAME>segment provides a name for your policy library.
- The repository description should contain a short sentence describing the purpose of the policy library. The Terraform Registry displays this description in search results and on the policy library's details page.
The GitHub repository must include a
sentinel.hcl file at its root level that contains the names and file locations for the policies and policy modules included in the policy library. The Terraform Registry ignores any policy files in the repository that are not listed in the file.
sentinel.hcl file must follow the Sentinel CLI Configuration File Syntax with two deviations:
- Remote sources for policies and policy modules are not allowed.
enforcement_levelfor a policy is not required. The Terraform Registry ignores this information if included.
The Terraform Registry uses tags to identify versions of policy libraries. Version tag names must be a semantic version, which can optionally be prefixed with a
v. For example,
0.9.2 are both acceptable. To publish a new policy library, at least one acceptable tag must be present. The Terraform Registry ignores tags that do not match these conventions.
Documenting a Policy Library
The Terraform Registry displays documentation for policy libraries from Markdown files in your GitHub repository. Markdown files are rendered similarly in the Terraform Registry to how they are rendered on GitHub.
Markdown documents should be in the following locations within the repository. The Terraform Registry ignores Markdown files stored elsewhere.
|Index page for the policy library.|
|Description of a single policy.|
|Description of a single policy module.|
<policy name> and
<module name> in the Markdown filenames must match the names of
module blocks in the library's
Publishing to the Registry
Before you publish, review the policy library categories on the Terraform Registry. Categories are general themes that can help users find policies that are relevant to their use case. We recommend designing your policy libraries to target a specific category, like networking rules or storage security. This helps the community find useful policies more easily.
To publish a policy library to the Terraform Registry:
- Ensure that your policy library's repository meets the requirements.
- If a GitHub organization owns the repository, verify that the Terraform Registry OAuth app has access to the organization. Go to your GitHub Settings and select the Terraform Registry Application under Authorized OAuth Apps to confirm.
- Sign in to the Terraform Registry with a GitHub account.
- Select Publish > Policy Library.
- Select the repository you would like to publish.
- Choose the category for your policy library that most closely matches the types of infrastructure relevant to your policies.
- (Optional) Associate your policy library with a set of Terraform providers. You may choose up to 3 publicly-available providers to indicate which types of Terraform resources are relevant to your policies.
- Click Publish Policy Library.
The policy library is now publicly available on the Terraform Registry.
Releasing Policy Library Versions
When you publish a policy library, the Terraform Registry creates a webhook in your GitHub repository that is subscribed to the
push event. The webhook informs the Terraform Registry when you create new tags in the repository and the Terraform Registry automatically updates to include the new policy library version.
To repair a broken or missing webhook connection, go to your policy library on the Terraform Registry and select Manage Policy Library > Resync Library. After a few seconds, the Terraform Registry adds a new webhook to your GitHub repository.
We recommend publishing new versions to fix bugs instead of editing old versions of your policy library. When you edit the files in an old version of the library, users who have been depending on those policies cannot use them until they review your changes and update their Sentinel configuration files.
Contact us at email@example.com for help publishing your policy library to the Terraform Registry.