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.

Requirements

Review the following before publishing a new policy library or policy library version.

GitHub Repository

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.

Sentinel File

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.

The sentinel.hcl file must follow the Sentinel CLI Configuration File Syntax with two deviations:

Remote sources for policies and policy modules are not allowed.
The enforcement_level for a policy is not required. The Terraform Registry ignores this information if included.

Version Tags

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, v1.0.4 and 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.

Directory Structure

Markdown documents should be in the following locations within the repository. The Terraform Registry ignores Markdown files stored elsewhere.

Location	Filename	Description
`/`	`README.md`	Index page for the policy library.
`docs/policies/`	`<policy name>.md`	Description of a single policy.
`docs/modules/`	`<module name>.md`	Description of a single policy module.

File Names

The <policy name> and <module name> in the Markdown filenames must match the names of policy and module blocks in the library's sentinel.hcl file.

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.

Note: All content published to the Terraform Registry is subject to HashiCorp's terms of use. You can review these terms at https://registry.terraform.io/terms.

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.

Removing a Policy Library

The owner of a policy library can remove that library from the Terraform Registry. Please be aware that we do not recommend removing anything from the Registry unless it contains a critical flaw.

To remove a policy library, navigate to your policy library's page and select Delete library from the dropdown menu.