Skip to content

Start runs from an agent or GitHub

Choose where the task should execute:

Execution Agent command GitHub integration Availability
Your machine or runner repo-maintainer run --task task.md --json Reusable maintenance workflow and .maintainer.yml Available now
Repo Maintainer hosted runner repo-maintainer cloud submit --file hosted-run.yml --allow-paid Workflow that submits a hosted task YAML Implemented in the hosted preview branch; public execution is not enabled yet

Both return work for review. Submitting a job does not mean it passed its checks. Local runs return a result when execution ends; hosted submission returns a queued run ID. The hosted service does not push, open PRs or merge changes.

Agents on your own infrastructure

Install the CLI, configure the target repository and verify the setup:

repo-maintainer check --repo /path/to/repository --json
repo-maintainer run --repo /path/to/repository --task task.md --json

An agent can also pipe task text into run --task - --json, or supply a complete JSON request using run --request - --json. See the CLI request format. Keys belong in the environment. A real run can use paid inference; check does not.

For scheduled or manually triggered GitHub maintenance, start with the existing reusable workflow and self-hosted caller example. The same workflow supports GitHub-hosted runners with runner_labels: '["ubuntu-latest"]'. Set config_path: .maintainer.yml, pin both workflow references to the same reviewed commit, and configure your model secret. The workflow can publish a PR after its checks pass; dry_run: true skips publication but still calls the model. Follow the GitHub setup prompt to adapt it.

Hosted CLI

Preview: these commands require a CLI revision containing the cloud subcommand and an enabled hosted backend. The current public website serves a static demonstration and returns an unavailable error for submissions. Check hosted deployment status before connecting secrets.

Install the reviewed preview CLI (Rust 1.89+ and Git required):

cargo install --git https://github.com/djsydney04/repo_maintainer --rev bc0102fdab5c4ffc48566db82c416d218b519179 --locked
repo-maintainer cloud --help

Use this same full revision for the REPO_MAINTAINER_REF Actions variable below.

Once enabled, sign in to the workspace, connect GitHub and your OpenAI API key, then open Connections → Automation tokens. Create a token for one repository with a 1–30 day lifetime (7 days by default). Copy it immediately into your secret manager or a GitHub Actions secret named REPO_MAINTAINER_TOKEN. It cannot be retrieved later. Revoke it from the same panel if no longer needed.

Tokens can submit, list, inspect, cancel and download runs for their repository. They cannot access other repositories, read provider keys, change connections or create more tokens. They use your existing hosted account's API credits and run allowances. Revoking a token prevents new API requests; it does not cancel already accepted jobs. Cancel those separately in the workspace.

Create hosted-run.yml in the repository you want to maintain:

repository: your-org/your-repository
task: |
  Fix one reproducible bug and add a regression test.
  Preserve the public interface. Return the patch for human review.
checks:
  - [git, diff, --check]
  - [node, --test]

Replace the repository and test commands. This is a hosted submission file, not the local engine's .maintainer.yml. Checks are argument arrays, not shell strings. The hosted image has Git, Node and Python; dependency downloads are restricted. The service pins the repository's default branch at acceptance; it does not upload your working tree or use the invoking workflow's branch.

Load REPO_MAINTAINER_TOKEN through your secret manager, then run:

# No network, credentials or model calls:
repo-maintainer cloud check --file hosted-run.yml

# Queues one task and authorizes its inference costs:
repo-maintainer cloud submit --file hosted-run.yml --allow-paid

repo-maintainer cloud list
repo-maintainer cloud status RUN_ID
repo-maintainer cloud cancel RUN_ID
repo-maintainer cloud download RUN_ID result --output result.json
repo-maintainer cloud download RUN_ID patch --output proposal.patch

Replace RUN_ID with the returned UUID. Downloads are available after completion and refuse to overwrite existing files. Review status, outcome and the report before applying a patch. A successful status command only means the API request succeeded; inspect the job to determine whether execution succeeded.

Commands print one JSON object with schema_version: 1. They exit 0 on a successful API operation (or offline validation), 1 on an execution/API error. Argument parser errors exit 2 and print usage. There is no automatic retry or polling. Submission prints its request key to stderr before contacting the service and includes it in successful JSON. If the connection fails, retry with the same --request-key to avoid creating a duplicate paid run. Reuse a key only for the same task.

For a separate deployment, set REPO_MAINTAINER_URL to its trusted HTTPS origin; HTTP is accepted only for local development on loopback. Redirects are refused so a server cannot redirect your automation token to another destination.

Submit from a GitHub YAML workflow

Copy the hosted workflow example into .github/workflows/hosted-maintenance.yml and the run file above into .github/hosted-run.yml on your default branch. Set:

  • Actions secret REPO_MAINTAINER_TOKEN: the token limited to this repository.
  • Actions variable REPO_MAINTAINER_REF: the full reviewed commit SHA containing the hosted CLI. The workflow installs that exact source revision.

Run Submit hosted maintenance manually and select the paid-inference checkbox. The workflow validates the file, submits one job, and saves submission.json as an Actions artifact. It does not wait for the hosted job or publish its patch. Rerunning the same Actions run reuses its request key; start a new workflow run when you intend to create another task. Do not add pull_request_target or feed unreviewed issue/PR text into shell commands.

This preview requires a current GitHub user connection. GitHub access tokens can expire even while an automation token is valid; reconnect in the workspace if the API reports that the connection is expiring. Unattended hosted schedules need refresh/installation-token support before they can run reliably. Use the existing self-hosted workflow for recurring maintenance today. See GitHub's token lifetime and refresh documentation.

Agent setup prompt

Prepare Repo Maintainer automation for this repository. Read
https://repomaintainer.com/docs/automation/ and inspect existing project instructions,
CI, runtime and tests. Identify whether execution should use our own runner or the
hosted service, and report hosted readiness before relying on it.

Preserve existing maintenance configuration. For local execution, prepare
.maintainer.yml and a task file, then run repo-maintainer check. For hosted execution,
prepare a hosted-run.yml with this repository and real check commands, then run
repo-maintainer cloud check --file hosted-run.yml. If GitHub integration is requested,
add the corresponding manual workflow, pin the maintainer revision and document
required secret names without printing their values. Use a repository-scoped token.

Do not submit a paid task, enable a schedule, broaden repository permissions or
publish a patch during this setup-only task. Show the diff, validation results,
missing setup and the exact command or workflow for the first intentional run.