The package file is the primary entry point for defining the business logic for building, testing and deploying an application with Ocuroot. Package files can be placed in any directory (we love monorepos), and must have the name package.ocu.star. When a package file is placed in a directory, Ocuroot will automatically monitor the files in that directory and its subdirectories for changes. When a file is changed, Ocuroot will execute builds and subsequent deployments as needed to release the changes.

​
The package function

A package file may define multiple packages. The package function is used to define each individual package. As an example, the below package file will define a single package named my_package: 
load("github.com/ocuroot/sdk/v0/package.star", "package")
load("github.com/ocuroot/sdk/v0/policy.star", "ready", "later")

def build(ctx):
  # Build code goes here
  # ... 
  pass

def deploy(ctx):
  # Deployment code goes here
  # ...  

  # Mark the build as deployed to staging
  if ctx.environment.attributes.get("type") == "staging":
    ctx.build.annotations["staged"] = "true"

def destroy(ctx):
  # Code to tear down the package in this evironment goes here
  # ...

def policy(ctx):
  # Only deploy to production after successfully deploying to staging
  if ctx.environment.attributes.get("type") == "prod" and ctx.build.annotations.get("staged") != "true":
    return later()
 
  return ready()

package(
  name="my_package",
  build=build,
  policy=policy,
  deploy=deploy,
  destroy=destroy
)
The above defines three key functions for the package:
  • build - defines the build logic for the package
  • deploy - defines the deployment logic for the package
  • policy - defines the deployment policy for the package

​
About policy functions

The policy function can be thought of as the “glue” between the build and deploy functions. This function is executed against every environment after any build or deployment that affects this package. If the policy function returns later(), this indicates that the build has not yet met the criteria for deployment to this environment. In this example above, this is returned for the production environment if the package has not yet been deployed to staging. If the policy function returns ready(), then the package will be deployed to the environment. If the policy function returns skip(), then the package will not be deployed to this environment. If a previous build of this package is already deployed to this environment, it will be destroyed.