Quickstart

This quickstart builds a workflow that reads a GitHub repository and plans a change to it. You write it, run it on your machine in the runner container, and then sync the same file to OutcomeCI.

You need Python 3.11 or newer, Docker, a Codex login (codex login), and a GitHub token that can read the repository you point it at.

Install

Install OutcomeCI with Homebrew:

brew install outcomeci/tap/outcomeci-cli

Or use pipx to keep it isolated from your project dependencies:

pipx install outcomeci-cli

If pipx is not already installed, follow the official pipx installation guide.

Confirm that the command is available:

oci --help

Create the workflow

From the repository you want to keep the workflow in, run:

oci init

This creates:

• outcome.yml, the workflow;
• .outcomeci/instructions/investigate.md and plan.md, the instructions for its two steps; and
• .outcomeci/request.json, a sample request to run it with.

outcome.yml is an outcomeci.workflow/v1 file:

apiVersion: outcomeci.workflow/v1
name: default
 
trigger: manual
 
secrets:
  github: vault:github
 
apis:
  github: {uses: github, auth: secrets.github}
 
reasoning:
  default: {runner: codex}
 
steps:
  - investigate:
      reason: investigate.md
      from: trigger
      can:
        - github.read: {repo: trigger.repo}
      returns:
        findings: [{path: string, note: string}]
 
  - plan:
      reason: plan.md
      with: [trigger, investigate.findings]
      returns:
        plan: {summary, steps: [string]}

The investigate step may read from GitHub, but only inside the repository the request names. The plan step has no API access at all; it works from the request and the findings. See Write a workflow for every field.

Check the file at any point with:

oci validate

Store the GitHub token

The workflow names its secret vault:github. Create a local Vault and store the token under that name, piping it through stdin so it stays out of your shell history:

oci vault local init
printf %s "$GITHUB_TOKEN" | oci vault local put github --value-stdin

The Vault is encrypted in .outcomeci/vault.enc, which init adds to .gitignore. Its key stays in ~/.config/outcomeci/vault-keys/. See Vault.

Run it

Edit .outcomeci/request.json so repo names a repository your token can read:

{
  "request": "Add a /health endpoint that returns 200 when the service is up.",
  "repo": {"owner": "your-org", "name": "your-repo"}
}

Then run the workflow in the runner container:

oci workflow run --payload .outcomeci/request.json --auto-continue

The payload becomes the run's trigger. --auto-continue runs every step; without it, the run stops after the first one. The command prints the run's final state:

{
  "run_id": "20260929051715962131-manual-received",
  "status": "completed",
  "completed_steps": ["investigate", "plan"],
  "agent": "codex"
}

Each step's result is in .outcomeci/outcomes/<run-id>/<step>/outputs.json, and every GitHub call the run made, with its status, is in .outcomeci/.broker/<run-id>/journal.json. See Run in the container.

Change the instructions, the grants, or the steps, and run again until the result is what you want.

Take it online

Cloud runs start from email, webhooks, or a schedule, so give the workflow one of those triggers. A weekly schedule has no request payload, so the steps name the repository themselves:

trigger: {type: cron, expression: "0 9 * * 1", timezone: America/New_York}
 
steps:
  - investigate:
      reason: investigate.md
      can:
        - github.read: {repo: your-org/your-repo}
      returns:
        findings: [{path: string, note: string}]
 
  - plan:
      reason: plan.md
      with: investigate.findings
      returns:
        plan: {summary, steps: [string]}

Update the instructions to match, then sign in and sync the workflow:

oci auth login
oci workflow sync outcome.yml --workspace-id WORKSPACE_ID --create

Sync uploads outcome.yml and the files under .outcomeci/, never the local Vault, the broker journals, or run outcomes. It prints the new workflow's ID.

Store the token in the workspace Vault under the same name, and grant it to the workflow:

printf %s "$GITHUB_TOKEN" | oci vault put github \
  --workspace-id WORKSPACE_ID --value-stdin --workflow-id WORKFLOW_ID

Finally, connect a Codex account under Vault → Agents in the dashboard. The schedule starts runs on managed runners from the next Monday at 9

Next

Learn every field a workflow can use.