Skip to main content
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.

​
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.
  • 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 and Containers), 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 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.
  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.
  • 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.