The policy module provides return values for the policy function, allowing you to control deployment behavior based on conditions.

​
Allowed in

  • policy

​
Usage

Load the module:

load("github.com/ocuroot/sdk/v0/policy.star", "skip", "later", "ready", "static", "dependency")

​
Example

def policy(ctx):
    # Skip deployment if package is marked as dev-only
    if ctx.build.annotations.get("dev_only") == "true" and ctx.environment.name == "prod":
        return skip()
    
    # Wait for staging if deploying to prod
    if ctx.environment.attributes.get("type") == "prod" and ctx.build.annotations.get("staged") != "true":
        return later("Waiting for staging deployment")
    
    # Ready to deploy with dependencies
    return ready(
        inputs={
            # Static configuration
            "config_version": static("v2"),
            
            # Dependencies from other packages
            "api_url": dependency(package="api-service", output="url"),
            "db_secret": dependency(package="database", secret_name="credentials"),
        },
        # Valid after 1 hour
        valid=after("1h"),
    )

​
API Reference

​
ready(inputs=, valid=None)

Returns a value indicating that the current build is ready to be deployed in the current environment.

Arguments

  • inputs: Dictionary mapping string names to input values from static() or dependency()
  • valid: Time at which this deployment will be considered valid (future deployments will be paused until this time)

Returns

  • Policy result indicating deployment readiness

​
later(msg="")

Returns a value indicating that the deployment cannot proceed now but will be able to proceed when certain conditions are met.

Arguments

  • msg: Message explaining what is blocking the deployment

Returns

  • Policy result indicating deployment should be retried later

​
skip()

Returns a value indicating this package should not be deployed in the current environment. If a build of this package is already deployed, it will be destroyed.

Returns

  • Policy result indicating deployment should be skipped

​
static(value)

Specifies a static input value to be passed into the ready function.

Arguments

  • value: The static value to pass into the ready function

Returns

  • Input specification for use in ready()

​
dependency(package, output=None, repo_id=None, environment=None, secret_name=None)

Specifies a dependency input value to be passed into the ready function.

Arguments

  • package: Package name of the dependency (cannot be current package)
  • repo_id: Optional repository ID containing the dependency (defaults to current repository)
  • environment: Optional environment where dependency was built
  • secret_name: Name of secret to use as input value (mutually exclusive with output)
  • output: Name of deployment output to use as input value (mutually exclusive with secret_name)

Returns

  • Input specification for use in ready()

​
Stubs

def ready(inputs={}, valid=None):
    """
    Returns a value indicating that the current build is ready to be deployed in the current environment.

    Args:
        inputs: Inputs to the deploy function. A dictionary mapping string names to input values from the static or dependency functions.
        valid: The time at which this deployment will be considered valid. If this is in the future, the deployment will be paused until this time.
    """
    pass

def later(msg=""):
    """
    Returns a value indicating that the deployment cannot proceed now, but will be able to proceed when certain conditions are met.

    Args:
        msg: A message to display to the user indicating what is blocking the deployment.
    """
    pass

def skip():
    """
    Returns a value indicating that this package should not be deployed in the current environment.
    If a build of this package is already deployed, it will be destroyed.
    """
    pass

def static(value):
    """
    Specifies a static input value to be passed into the ready function.

    Args:
        value: The value to pass into the ready function.
    """
    pass

def dependency(
    package,
    output,
    repo_id=None,
    environment=None,
    secret_name=None,
):
    """
    Specifies a dependency input value to be passed into the ready function.

    Args:
        package: The package name of the dependency to be used. May not be the current package.
        repo_id: The ID of the repository containing the dependency. Defaults to the current repository.
        environment: The environment in which the dependency was built.
        secret_name: The name of a secret to be used as the input value. One of `output` or `secret_name` must be specified.
        output: The name of a deployment output to be used as the input value. One of `output` or `secret_name` must be specified.
    """
    pass