Run jobs from your git repository

Connect a repository to Komputo and its git events — pushes, pull requests, releases — trigger jobs automatically. Results are reported back to your commits as status checks, so a job can gate a pull request without spending any GitHub Actions runner minutes. The work runs on Komputo; GitHub only sends a webhook and receives a status.

You define workflows in one of two places, and you can mix them:

• On the platform — from the Workflows page in the app, the CLI, or MCP.
• In your repository — a .komputo/workflows.yaml file committed with your code.

When both exist for a repository, the file wins: a committed file is the authoritative source, and the platform-authored workflows it supersedes are shown as shadowed. Every run records where its configuration came from — file or platform — so there is never any ambiguity.

Connect a repository

In the app, open Workflows → Connect a repo and enter owner/name. You get a webhook URL and a secret (shown once). In your repository’s Settings → Webhooks → Add webhook, paste the URL, set the secret, choose content type application/json, and select the push, pull request, and release events.

From the CLI:

komputo workflow connect owner/name --token github_pat_xxx

The access token

To run a job, Komputo reads the job spec referenced by a workflow from your repository. Provide a repository access token (a fine-grained PAT with read access to contents) when connecting. Without a token, matched workflows are recorded as pending rather than run — useful to validate triggers before granting access. The token is encrypted at rest and used only to read specs and post statuses.

Define a workflow

A workflow binds triggers to a job spec to run. The spec is a normal job spec committed in your repo; the workflow only decides when it runs.

.komputo/workflows.yaml

version: 1
workflows:
  - name: eval-on-pr
    on:
      pull_request:
        branches: [main]
        paths: ["models/**", "evals/**"]
    run: .komputo/eval.yaml
    report: { mode: check, gate: true }
    concurrency: { group: pr-eval, cancel_in_progress: true }

  - name: nightly-train
    on:
      schedule: { cron: "0 2 * * *" }
    run: .komputo/train.yaml

To author the same thing on the platform, open a connection in the Workflows page and Add workflow (paste one definition), or:

komputo workflow add <connection-id> ./eval-workflow.yaml

Triggers

A workflow must declare at least one trigger under on:

Trigger	Fires on	Options
push	A commit pushed to a branch	branches, paths
pull_request	Pull-request activity	types, branches (base branch), paths
release	A release	types
schedule	A cron schedule (UTC)	cron (5-field)
manual	A manual trigger from the platform or CLI	—

branches and paths use glob patterns: * matches within a path segment, ** matches across segments (including /), and ? matches a single character.

Reporting back

report.mode controls how a run surfaces its outcome:

mode	Effect
check	Posts a commit status. Set gate: true to block the merge.
comment	Leaves a pull-request comment.
none	Reports nowhere (fire-and-forget).

With mode: check, Komputo posts a pending status when the job is submitted and success/failure when it finishes — so the check on your commit tracks the job, with no runner minutes spent on your side.

Watch runs

The Workflows page lists recent runs per connection — which workflow matched, its source (file or platform), the event, and the status. From the CLI:

komputo workflow runs <connection-id>

When to use the GitHub Action instead

The Komputo GitHub Action is the fallback for repositories that are not connected, or when you want a job to block a step inside an existing GitHub Actions pipeline. By default it submits and returns immediately (seconds of runner time); set wait: true only when you want the step to block on the job. A connected repository needs no action and no runner minutes at all.