Policies

What is a policy?

Policies define the conditions under which approval actions are granted, denied, or flagged for manual review.

• They help ensure that approvals align with business rules, security requirements, and compliance policies.
• By leveraging metadata, policies can evaluate real-time information to make approval decisions.

Using metadata in policies

Policies can leverage metadata from different entities based on the action being evaluated. This allows for precise, context-aware approval decisions. For example, you can enforce approvals based on:

• Code coverage in a build process.
• The security status of a deployment.
• Whether a resource supports auto-scaling.
• And more.

By using metadata, policies dynamically adapt to specific requirements.

For more details, see Metadata.

Available entities for policy configuration

The following table shows which entities provide metadata for different approval actions:

Approval actions	Entities whose metadata is available for policy configuration
deployment:create	deployment, scope, release, build, application, namespace, account, organization
scope:create	scope, application, namespace, account, organization
scope:write	scope, application, namespace, account, organization
scope:delete	scope, application, namespace, account, organization
scope:stop	scope, application, namespace, account, organization

This means that once you've defined a policy using metadata, you can associate it with an approval action based on the entities it references.

For example, if your policy relies on scope metadata, you can link it to any approval action listed above, as scope metadata is broadly available. However, if your policy references build metadata—like in the example below—it can only be applied to a deployment:create action, since build metadata is exclusive to deployments.

Adding metadata to policies

Before using metadata in policies, you need to define a metadata specification. This outlines the structure and rules for the data you want to enforce.

For example, the following metadata specification tracks code coverage in a build:

{
  "name": "Coverage",
  "description": "Build coverage report",
  "nrn": "organization=1",
  "entity": "build",
  "metadata": "coverage",
  "schema": {
    "type": "object",
    "properties": {
      "percent": {
        "type": "number",
        "default": 0,
        "minimum": 80,
        "maximum": 100
      },
      "report": {
        "type": "string",
        "format": "uri"
      }
    },
    "required": ["percent", "report"],
    "additionalProperties": false
  }
}

See our API reference for more info on how to create a metadata specification.

Now that the specification is created, policies can reference this metadata to enforce coverage requirements before approving deployments.

Create a policy

To create a policy, send a POST request to our Approval policy endpoint. The conditions object defines the rules that must be met for an approval action to proceed.

Example: Enforcing approval conditions for deployments

The following policy ensures that deployments are only approved if:

• Code coverage is at least 80%.
• Security issues do not exceed 4.
• The resource supports auto-scaling.
• The environment is either dev or qa.

POST - Create a policy

curl -L 'https://api.nullplatform.com/approval/policy' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "name": "Enforce coverage, security, and scaling for deployments",
  "conditions": {
    "build.metadata.coverage.percent": { "$gte": 80 },
    "build.metadata.security.issues": { "$lte": 4 },
    "scope.capabilities.auto_scaling": true,
    "$or": [
      { "scope.dimensions.environment": "dev" },
      { "scope.dimensions.environment": "qa" }
    ]
  }
}

Conditions' syntax

Policies use MongoDB syntax for conditions, allowing you to create flexible and complex rules.

Example response

If the policy is successfully created, you’ll receive a response like this:

Response payload

{
  "id": 12345,  // Save the policy ID for the next steps
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "name": "Enforce coverage, security, and scaling for deployments",
  "conditions": {
    "build.metadata.coverage": { "$gte": 80 },
    "build.metadata.security.issues": { "$lte": 4 },
    "scope.capabilities.auto_scaling": true,
    "$or": [
      { "scope.dimensions.environment": "dev" },
      { "scope.dimensions.environment": "qa" }
    ]
  }
}

tip

The id field contains the unique policy ID. Be sure to save it, as you'll need it in the next steps.

What's next

Now that you've created a policy, the next step is to link it to an approval action so it can be evaluated so it can be evaluated.

Learn how to associate a policy with an action.