Delivery Model¶

This page describes how Imbi records what a project ships: commits, pull requests, tags, releases, deployments, blockers, and drift. It also describes how each record gets into Imbi. For how to use these features in the UI, see Releases and deployments and Drift.

Data model¶

flowchart LR
    subgraph graph[Postgres graph]
        P[Project]
        PT[ProjectType<br/>deployable or releasable]
        E[Environment<br/>sort_order, terminal,<br/>can_deploy, can_promote,<br/>allow_autonomous]
        R[Release<br/>tag, committish,<br/>drift_detected]
        D[Deployment<br/>status, external_run_id]
        B[Blocker<br/>type, scope, status]
    end
    subgraph ch[ClickHouse]
        C[(commits)]
        T[(tags)]
        PR[(pull_requests)]
        CD[(commit_drift)]
        OL[(operations_log)]
        RC[(release_components)]
    end
    P -- TYPE --> PT
    P -- HAS_RELEASE --> R
    D -- BELONGS_TO --> P
    D -- TARGETS --> E
    R -- HAS_DEPLOYMENT --> D
    R -- BLOCKED_BY --> B
    P -- "DEPLOYED_IN<br/>current_release" --> E
    P -.-> C & T & PR & CD & OL
    R -.-> RC

In the graph¶

A Deployment can exist before its Release. The gateway can record a deployment for a project and an environment when no release matches yet. The deployment-sweep maintenance operation attaches it to the release later.

Older deployments are entries in a deployments array on a (Release)-[:DEPLOYED_TO]->(Environment) edge. Nothing writes that array now. The read paths combine the old entries with the Deployment nodes.

In ClickHouse¶

All of these tables get their rows through Iggy. See Events and analytics.

Deploy and promote¶

A user or a principal starts both actions with POST /organizations/{org_slug}/projects/{project_id}/deployments (under the imbi-api route prefix). imbi-api resolves the deployment plugin of the project (for example GitHub) and calls it.

• Deploy (action: deploy or redeploy) ships a commit or a tag to one environment. A rollback is a redeploy of an earlier ref.
• Promote (action: promote) ships the build that runs in one environment to the next one:
  • If the ref is already a tag, imbi-api starts the deployment of that tag.
  • If the ref is a commit SHA, imbi-api cuts a new tag at the commit, upserts the Release, and starts the deployment of the tag.
  • If the project has a release workflow (the artifact_workflow option of the deployment capability), imbi-api starts that workflow and returns. The workflow builds the artifact and cuts the tag. The release promote worker in imbi-api watches the build. When the build succeeds, the worker refreshes the release, creates the deployment, and watches the rollout. When the build fails, the worker blocks the release. The UI reads the progress from the promote_* properties of the project.

The remote release (for example a GitHub Release) is not created at promote time. It is published after the rollout succeeds.

Before it starts an action, imbi-api checks these conditions:

1. The environment allows the action (can_deploy or can_promote), and allow_autonomous when the principal has no user.
2. No open blocker refuses the release.
3. For a promote, no other release of the project is in flight.
4. CI did not fail for the commit.

CI gating¶

imbi-api asks the deployment plugin for the CI status of the commit (get_check_status). For a promote, it asks about the commit on the default branch, not about the tag.

• Only fail gates. warn (a cancelled or stale run) and unknown (no CI, or no access to the check runs) do not gate.
• On fail, imbi-api returns 409. To continue, the caller sends the request again with acknowledge_ci_failure: true. imbi-api records the override on the release.
• A principal with no user cannot acknowledge a CI failure. That flag states that a person looked at the failed checks.

Blockers¶

A Blocker hangs off a release through BLOCKED_BY. While a blocker is open, imbi-api refuses every deploy and promote of that release with 409, and lists the blockers.

These parts of Imbi file blockers:

• A user, from the UI or the API.
• The block_release gateway action.
• The release promote worker, when a release build fails.
• The drift ingest, when CI reports drift for a tagged release (type drift). A later verdict that is not true resolves it.

Current release of an environment¶

The current_release property on DEPLOYED_IN says which release runs in each environment. Two writers set it:

• A successful deployment event. The pointer moves to the release of the event, but only when the event is newer than the stored time. Thus a replay of an old event cannot move it back.
• Deployment sync. It asks the plugin which deployment is active in each environment. When the plugin knows, the pointer moves to that release, or clears when nothing is active. When the plugin does not know, or fails, the pointer stays as it is.

How records get in¶

• An on-demand sync puts a job on a Valkey stream. A worker in imbi-api runs it with the service credential of the integration, and writes the status of the last run on the Project node. The UI reads that status. See Background workers.
• A webhook delivers each deployment status once. The gateway repeats a deployment write that imbi-api refuses with a 5xx, but only when the event has a run ID, because Imbi merges deployments on that ID. The promote watcher repeats its close-out after a graph write conflict, and closes the operations-log entry of the rollout.
• When the current releases of a project are read (the Deployments tab), Imbi asks the plugin about each deployment that is still running. When one has finished, Imbi records the result, and the same response shows it.
• deployment-sweep asks the remote about each deployment that is still running after 30 minutes. It marks a deployment failed when nothing can resolve it for a week. It also attaches early deployments to their release, and reads drift verdicts for releases that have none.
• Imbi does not schedule deployment-sweep by itself. Run it from the Maintenance page, or create an imbi-scheduler task that calls it. See Maintenance.
• The webhook actions run only when the integration has the webhook-actions capability turned on and a webhook rule selects them. See Webhooks.

Drift¶

Imbi uses the word "drift" for three different things. Do not mix them.

Environment drift¶

Imbi takes the environments of the organization in sort_order and splits them into pipelines at each terminal environment. Each pair of adjacent environments in a pipeline is a promotion step. A pair drifts when the two environments run different commits. When both sides have a commit SHA, Imbi compares the SHAs, so two tags on the same commit do not drift. Otherwise it compares the tag, or the SHA when there is no tag.

A missing release on one side counts as drift.

Release drift¶

A releasable project drifts when the default branch has commits after the latest tag. The latest tag is the highest version, as on the Releases tab of the project.

CI drift verdicts¶

CI writes a git note for each commit, in the refs/notes/imbi-drift namespace, with JSON such as {"drift_detected": false}. Imbi reads the notes in three ways:

1. A push to the notes ref reaches the gateway. The update_release_drift action sends the old and new values of the ref to imbi-api, which reads the changed notes.
2. Commit sync reads the notes of the commits it records, except the commits that already have a verdict.
3. deployment-sweep reads the notes for releases that have no verdict yet. It asks again after 24 hours at the earliest.

Each verdict becomes a row in commit_drift. A verdict for the commit of a tagged release also sets Release.drift_detected, and true files the drift blocker. drift_detected is null until Imbi sees a note.

The verdict rule¶

The verdicts filter the first two kinds of drift. A range of commits (the commits between two environments, or after the latest tag) is clean only when every commit in it has the verdict false:

• A true verdict shows drift.
• A commit with no verdict shows drift.
• When imbi-api cannot read the verdicts, the range shows drift.

Thus a range of commits that CI never checked stays in the list until someone promotes past it.

The projects list counts environment drift and release drift. It does not count Release.drift_detected. A project type that is neither deployable nor releasable shows no drift.