​

Workflow

The journey for any change in Ocuroot begins with a developer working in a Git repo. Once a commit is pushed, Ocuroot will kick off a Deliver operation, automatically identifying what needs to be built and tested based on changes included in the commit.

The output for the Deliver operation will be one or more Build records and updates to the Target State. This is when the Sync operations take over.

A Sync will identify differences between the Target State and the actual deployed state in your Environments and perform any required actions to ensure they match. This may result in further changes to the Target State as a result of your Policy rules, resulting in further Syncs.

​

Components

Ocuroot consists of two main components, a server and a client.

The server maintains state, provides a UI and orchestrates deployments and other tasks needed to keep everything up to date. The server is backed by a Postgres database and uses an S3-compatible bucket for additional storage.

The client is a small CLI application that allows an end user to interact with Ocuroot directly, as well as running Deliver and Sync operations.

Typically, Deliver and Sync operations will run on an existing CI platform like GitHub Actions or TeamCity, which will act based on events triggered by Git repos, or requests from the Ocuroot server. However, for ease of testing and during emergencies, a developer can run them from a local machine.

​

Terminology

Term	Description
Environment	A distinct “location” where Builds of Packages may be deployed. For example, you may have a staging and production Environment.
Repo	A single Git repository that contains one or more Packages.
Package	A collection of code that may be built and deployed independantly.
Change	A snapshot of the state of a Git repository at a given time. This may specify a commit and optionally an uncommitted diff on top of it.
Build	The output of building a Package at a specific Change.
Deployment	The result of deploying a Package to an Environment. This may be depended on by downstream Deployments.
Policy	Custom rules that define whether or not a Build may be deployed to an environment.
Target	The desired state of a Package within an Environment, which may include a Build and a set of inputs, or the expectation that the Package is not running.

​

State Management

Core to Ocuroot’s orchestration of your CI/CD processes is the concept of state management. Ocuroot will track information about your Changes, Builds and Deployments to provide you with a detailed view of the entire lifecycle of a change, as well as fine-grained control of the automations surrounding them.

Builds have two kinds of state, Attributes and Annotations. Both are key-value pairs. An Attribute is created at build time and is immutable, an Annotation may be added when Ocuroot performs synchronization operations.

Attributes can be used to store assets and metadata about a build. They may include information like Docker image labels, version numbers or even tarballs for binaries.

Annotations may be used to control Policy. For example, you may add the annotation staged=true to indicate that your build has successfully deployed in a staging environment and may be deployed to production.

Deployments have Inputs and Outputs. Both are key-value pairs. Inputs can be used to modify the behavior of a deployment and can be obtained from the Outputs of other deployments in any environment. Both Inputs and Outputs can be stored as secrets.

​

YAML-free Configuration

All configuration files in Ocuroot are written in the Starlark language, a dialect of Python originally created for the Bazel build system.

Ocuroot uses the .ocu.star suffix to distinguish its configuration files from other source.

By implementing your configuration with imperative code, you can have a high degree of control over the behavior of your automations. Need to build binaries for multiple platforms at once? Easy! Just write a for loop.