> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ship a change and verify the release with your AI assistant

> Have your assistant take a reviewed change through merge, build and deployment, keeping what was merged, what was reported deployed and what is observed running apart, and stopping wherever a person has to decide.

Shipping a change is four separate facts, and your assistant should report
each one on its own:

1. **Merged.** The reviewed commit landed on the target branch.
2. **Built and published.** CI built the artifacts for that commit, such as
   container images, and pushed them.
3. **Reported deployed.** A deploy job says it applied those artifacts to an
   environment.
4. **Observed running.** Something independent of the deploy job saw the
   workload running.

These are distinct facts, each with its own evidence, and none of them implies
another. A green CI run, a tag or a deploy job's report doesn't establish that
a version is running. An observation of what is running doesn't establish
which commit it was built from. Give your assistant this page along with
[Use ReasonOS with your AI assistant](https://docs.reasonos.com/ai.md).

## Start with a request like this

> Change request 42 in the payments project was approved. If it's still
> mergeable at the head that was reviewed, tell me what merging needs and wait
> for my go-ahead. After it merges, follow the deploy to staging and tell me
> what you can and can't confirm about what is running there.

## Tools

On the managed ReasonOS MCP:

* `check_merge`: whether the request merges cleanly, its base and head
  commits, and what branch protection still requires.
* `merge_change_request`: merges the request. Pass `check_merge`'s `head_sha`
  and `base_sha` as `expected_head_sha` and `expected_base_sha`. `merge_stack`
  merges a stack bottom-up through the same checks.
* `ci_status`, `get_ci_run`, `get_ci_run_log`: the runs for a commit and how
  their jobs ended.
* `start_ci_run`: runs a workflow by hand on a branch. Only workflows with a
  `manual` trigger match. See [CI triggers](https://docs.reasonos.com/platform/ci.md).
* `list_deployment_reports`: what deploy jobs reported applying, per
  environment and commit. Each report is that job's claim and is always marked
  not verified.
* `list_runtime_observations`: what registered in-cluster observers saw
  running.
* `issue_evidence`: the evidence linked to an issue, including any deployment
  reports that match its commits exactly.

## Before you start

Find out how this project ships. Read its CI configuration and deploy targets
(see [Kubernetes](https://docs.reasonos.com/deploy/kubernetes.md) and [Containers](https://docs.reasonos.com/deploy/containers.md)),
and the project's own release notes or runbook if it has one. Answer these:

* Which workflow builds and pushes artifacts, and which deploys them? On which
  branches and triggers do they run?
* Which [environment](https://docs.reasonos.com/platform/ci.md#environments) does a deploy run in? An
  environment comes from the ref's branch pattern, not from anything the
  assistant chooses at run time.
* Does the deploy need migrations, configuration or secrets first? Secrets
  marked *protected refs only* are given only to runs on the default branch.
* What is the rollback, and who may run it?
* Does any observer report on the target environment?

If the project doesn't say, tell the person what is unknown instead of
guessing.

## The workflow

1. **Confirm the head that was reviewed.** Run `check_merge` and compare its
   `head_sha` with the commit that was approved. If the head moved, the review
   and checks were for an older commit. Stop and say so; see
   [Review a change](https://docs.reasonos.com/workflow/review-a-change.md).
2. **List what still blocks the merge.** `check_merge` names unmet rules:
   missing approvals, unresolved threads, required checks that failed or
   haven't run at this head. A check that hasn't run isn't a pass.
3. **Find out what the merge will set off.** A merge is a push to the target
   branch, and the project's workflows may build, publish images or deploy on
   that push. Read which workflows trigger on a push to the target and what
   their jobs do. Tell the person everything the merge will start.
4. **Ask before merging.** Merging is the person's decision, and so is
   everything it sets off. Merge only when the person has approved both the
   merge and the publication or deployment it causes, or when those triggers
   are verifiably held off first. Then call `merge_change_request` with both
   expected commits and record the merged commit it returns. Approval to merge
   alone is never approval to deploy.
5. **Follow the build.** Call `ci_status` with the merged commit as `sha` and
   the target branch as `ref`, waiting with `wait_seconds` if you need to. Report each required job as passed,
   failed, still running or not run. Note the artifacts the build pushed and
   their digests, when the log or a report names them.
6. **Follow the deploy.** If the deploy runs on its own, find its run. If the
   project deploys by hand and the person asks you to, run that workflow with
   `start_ci_run` and a `request_key` you choose. Then read
   `list_deployment_reports` with the environment and the full merged commit.
7. **Look for independent evidence.** Read `list_runtime_observations` and use
   the sources whose `environment` is the target. Check each source's state and
   freshness before relying on it. Compare the images the observer saw with the
   digests the build pushed. Report the rollout state exactly as the observer
   gives it, for example complete, progressing, mixed or unknown.
8. **Report the four facts separately.** Say what was merged, built, reported
   deployed and observed running, with the exact commit, digests, run numbers
   and times. Name each one you couldn't confirm.

## What each piece of evidence proves

* **A merge** proves the commit is on the target branch, nothing more.
* **A passing CI run** proves its jobs passed *for that commit*. A pass at an
  earlier commit doesn't count for a later one.
* **A deployment report** proves a deploy job *said* it applied those
  artifacts. ReasonOS ties its environment, commit and run to the job that
  filed it, so the job can't claim another commit. ReasonOS never checks the
  report against what is running, so it is always shown as not verified.
* **A runtime observation** is what a registered observer saw: the
  Deployment's rollout state and the image IDs its Pods report. Nothing yet
  links a running image to a source commit, so every observation's provenance
  is *unknown*. Matching digests is your comparison, not ReasonOS's
  verification. Say so.
* **A tag, a release note or a message** that a version is live proves
  nothing about what is running.

## Approval points

Reading merge checks, runs, reports and observations changes nothing. Ask the
person before you:

* merge, or merge a stack, including whatever builds, publications or
  deploys that merge triggers;
* start a deploy workflow by hand, or retry one;
* run a migration, change configuration or secrets, or roll back.

An earlier approval of the change isn't approval to deploy it. Approval to
merge doesn't cover a deploy the merge triggers unless the person approved
that too. Approval to deploy one environment isn't approval for another.

## When things go wrong

* **The head or base moved.** `merge_change_request` refuses the merge. Read
  `check_merge` again and go back to step 1. Don't drop the expected commits
  to get past it.
* **A required check hasn't run, or failed.** The merge is blocked. Report
  which check is missing or failed at this head. Don't start unrelated runs to
  turn things green.
* **The merge outcome is uncertain.** If ReasonOS says it couldn't confirm
  whether the merge landed, read the change request and target branch before
  doing anything else. If it says the merge landed but couldn't be recorded,
  merging again finishes the record without merging twice. See
  [Recover and resume](https://docs.reasonos.com/workflow/recover-and-resume.md).
* **A run started by hand does nothing.** If no workflow has a `manual`
  trigger, the run ends in error and says so. Report that; don't edit the
  workflow to make it run unless the person asks.
* **A start's answer is lost.** Send `start_ci_run` again with the same
  `request_key`: it answers the first attempt's event and starts nothing new.
  A new key starts a new run.
* **No deployment report.** Either the deploy hasn't run, it ran somewhere
  that doesn't file reports, or it failed before reporting. Read the run's log
  instead of assuming any of these.
* **No observer, or a stale one.** Say there is no independent evidence of
  what is running. The person may check the environment directly.
* **A partial or mixed rollout.** Report it as partial. Name the images seen
  and the state, and leave the next step to the person.
* **Rollback.** Treat a rollback as another deploy, of a known earlier commit
  or artifact. It needs the same approval and the same evidence afterwards.

## Limits today

* ReasonOS has no release, promote or rollback command. Deploying is running
  the project's own deploy targets, usually from a CI workflow.
* CI has no approval gate for deploy jobs. The only built-in guard is that
  *protected refs only* secrets go to runs on the default branch. Approval
  comes from the person, at the points above.
* Deploy jobs file reports themselves, through the CI runner's job API. The
  report format isn't a published customer contract yet. A project without a
  reporting step has no deployment reports.
* Observers are registered by a project admin in project settings, signed in
  to ReasonOS. An assistant's access token can't register one. Installing an
  observer in your cluster isn't covered here yet.
* No record links a running image to the commit it was built from, so
  ReasonOS can't yet state which commit is running.
* This page describes the current tools. A hosted deployment may run an
  earlier build: use the tools your connection actually offers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.