Skip to content

You are viewing documentation for Immuta version 2022.4.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

Approve to Promote Overview

Approve to Promote (ATP) helps platform owners ensure global policies are reviewed and approved before they are eligible for production environments. With ATP enabled, the Immuta application workflow guides policy authors to create, assess, and revise policies in development. When the policy author is ready for review, the approvers can inspect the policy and indicate their approval through the Immuta application. Once a policy has reached the configured number of approvals, the change becomes eligible for promotion. For instructions to enable this feature, see Enable Approve to Promote. To use the feature, see the Approve and Promote Policies to Production tutorial.


  • One Immuta instance per policy-authoring environment and production environment. SaaS instances should be hosted under separate domains.
  • Approve to Promote enabled only in the policy-authoring environment.
  • Immuta version 2022.3+.
  • Immuta CLI 1.1.0+.

Approve to Promote Process

When Approve to Promote is enabled, any Global Policies that are created, edited, or staged will go through this process:

  1. A Data Governor creates a Global Policy in the development environment.
  2. The policy author requests a review, and a notification is sent to approvers.
  3. The policy is reviewed by Data Owners and other Data Governors, who either request changes or approve the policy.
  4. Once the policy reaches the required number of approvals, a Data Governor promotes the policy through the Immuta CLI.
  5. A Data Governor saves the policy to the production environment though the Immuta CLI.

Policy Authoring

Users with the GOVERNANCE or CREATE_DATA_SOURCE permissions can create and edit Global Policies.

When ATP is enabled, policy changes will take effect in the policy-authoring environment before the policy is approved. This behavior allows users to iterate on these policies in the authoring environment before they are reviewed by others. When ready, the policy author requests a review from approvers through the Immuta policy builder user interface, who can then approve or request changes.

Once under review, the policy will display the approval history and progress.

Policy in Review

Data Governors and Data Owners can click a policy to see its status in the review process, approve it, or request changes to it.

Policy Review and Approval

Best Practice

Altering a policy during the approval process ends the review without making the policy eligible for promotion. Align on the compliance requirements and criteria outside the Immuta application through a corporate-defined workflow before authoring the policy. Once requirement agreement is reached, leverage Immuta ATP to record the outcome of that decision and stakeholder acceptance.

After the policy author requests for approval, the policy is in review. The review period ends when the approval threshold is met, a reviewer requests for changes, or the policy is modified. ATP requires the configured minimum number of reviewers to approve a policy before it can be promoted.

For example, if the ATP approval threshold is configured to require approvals from three users and a policy review receives 3 approvals, then the review has ended and no other reviewers can request for changes. However if the same policy receives two approvals, a third reviewer may end the review for rework by requesting changes.

Users with the following Immuta permissions can review and approve policies:

  • CREATE_DATA_SOURCE: Data Owners can author and approve Global Policies that apply to data sources they own, but they cannot approve their own policies.
  • GOVERNANCE: Governors can author and approve Global Policies, but they cannot approve their own policies.

When these users request changes to a policy, they are required to provide an explanation for the revision. Then, the request freezes the approval process until an update is made to the policy by a Data Governor. Users who previously approved the policy will need to re-approve the changes before the policy can be promoted.

Request Changes

When users approve a policy, they are prompted to provide an optional comment. After their approval, the policy status updates to show how many more approval are required.

Policy Approved

Policy Promotion

After a policy has been approved, Governors promote the policy through the Immuta CLI. The policy must then be cloned and saved to the production environment via the Immuta CLI. Once this has been completed, policies are marked as promoted in the UI.

Policy Promoted

Immuta does not prevent Governors from directly editing policies in production environments, so administrators should ensure that the GOVERNANCE permission is granted to a limited number of users in production environments to prevent policy changes that circumvent the approval process.


In the policy-authoring environment, no audit records are emitted by Immuta for approvals. However, when policies are promoted, audit records will be emitted for the following actions:

  • Global Policy created
  • Global Policy review requested
  • Global Policy change requested
  • Global Policy approval rescinded
  • Global Policy approved
  • Global Policy promoted

The policy references (PolicyKey) are stable across environments, as long as they are not modified manually after cloning the policies for promotion.


  • Immuta does not prevent users with the GOVERNANCE permission from editing policies directly in production without going through the approval workflow, so administrators should grant that permission to a limited number of users in the production environment.
  • Approval chains are not supported, so they must be coordinated outside Immuta.