Automatic CI improvements

How it works

1. Mirage observes successful CI runs and ranks promising opportunities.
2. A coding model proposes a bounded change, such as caching dependencies or adjusting build settings. Your subscription can provide this proposal through an investigator workflow on your owned Mirage Linux capacity.
3. Mirage runs baseline and candidate trials on separate service-funded capacity, preserving the original checks. Supported workflow changes are measured across the workflow graph.
4. Passing, repeatable improvements appear on your repository page with the tested patch, timings, and any CPU allocation tradeoff. Create pull request opens the tested change for normal GitHub review.

The current trial engine supports static Linux x64 Cargo and Node workflows with up to four jobs, including npm, Yarn, pnpm and Bun installs on reviewed tool versions. It can investigate caching, supported build settings, static job parallelism and runner sizing. Workflows needing secrets, private dependency credentials, matrices, services or artifact outputs are outside this initial trial scope. Setup does not guarantee a recommendation.

Before you start

You need:

• A private, active repository selected for the Mirage GitHub App.
• Repository manager access in Mirage, and GitHub permission to manage repository Actions secrets and review workflow pull requests.
• The GitHub App permissions needed to create workflow changes and pull requests. If Mirage asks you to approve an App permission update, do that on GitHub before continuing.
• Owned Mirage Linux x64 VM capacity shared with the repository's account. Investigators start only when the account has no unfinished jobs and resources for at least two default runner allocations, leaving headroom at dispatch. Proxmox runners describes one way to provide it.
• An eligible Claude Code or ChatGPT subscription, with access to the model you choose.

The investigator uses your subscription and owned CI capacity. Mirage funds the performance trials. Provider plan limits still apply. New normal jobs can arrive after admission; the headroom check is not a permanent capacity reservation.

1. Choose a repository and plan

1. Sign in to Mirage with GitHub, then connect the repository if it is not already listed.
2. Open Repos, select the repository, and find Verified improvements.
3. Expand Use your coding subscription. Choose Claude Code or Codex · ChatGPT.
4. Enter the exact model identifier available in your plan, and a daily proposal limit between 1 and 10. This is a cap on attempts, including failed attempts, per UTC day.
5. Select Create setup pull request. Open View setup pull request and leave it open while you add the provider's secrets below.

Only configure the provider you selected. Mirage opens a ready pull request containing .github/workflows/mirage-investigator.yml; it does not change your existing jobs.

2. Connect Claude Code

Install the official Claude Code client on a trusted machine and authenticate with your eligible subscription. Create a token:

claude setup-token

In GitHub, open the repository's Settings → Secrets and variables → Actions, then choose New repository secret. Set its name to CLAUDE_CODE_OAUTH_TOKEN and its value to the token. Keep the token out of source files, workflow YAML, caches and artifacts.

If you use the GitHub CLI, this command prompts for the value instead of putting it in your shell history. Replace OWNER/REPO with your repository:

gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo OWNER/REPO

Mirage uses the pinned official Claude Code client. See Claude Code GitHub Actions for subscription authentication and provider requirements.

2. Connect Codex / ChatGPT

Install the official Codex client on a trusted machine. Use a dedicated login for this repository's investigator, separate from your normal laptop login. The following commands select a separate auth directory and request file-backed credentials:

mkdir -m 700 "$HOME/.mirage-codex-investigator"
CODEX_HOME="$HOME/.mirage-codex-investigator" codex -c 'cli_auth_credentials_store="file"' login

Choose ChatGPT authentication. The investigator accepts ChatGPT subscription auth, rather than API-key auth. If you use several repositories, choose a different dedicated directory and login for each one.

Add MIRAGE_CODEX_AUTH_JSON as a repository Actions secret containing that directory's auth.json. With the GitHub CLI, read it directly into the secret:

gh secret set MIRAGE_CODEX_AUTH_JSON --repo OWNER/REPO < "$HOME/.mirage-codex-investigator/auth.json"

Create a fine-grained GitHub personal access token restricted to this repository, with the repository permission Secrets: Read and write. Use an expiry appropriate for your team, and complete any organization approval it needs. Store it as MIRAGE_CODEX_SECRET_WRITE_TOKEN:

gh secret set MIRAGE_CODEX_SECRET_WRITE_TOKEN --repo OWNER/REPO

That token lets the workflow save refreshed Codex auth back to MIRAGE_CODEX_AUTH_JSON after each run, including failed generation. The normal Actions GITHUB_TOKEN cannot update repository secrets. The coding model never receives the writer token.

Once uploaded, keep this login exclusive to the serialized investigator workflow. Do not keep using it on your laptop, copy it to another repository, or overwrite the secret with the original auth file after CI has refreshed it. If writeback fails, replace the writer token and add a fresh dedicated login before resuming. See Codex authentication and the trusted private CI guide.

3. Merge the setup pull request

Review the investigator workflow, confirm the required repository secrets exist, and merge the setup pull request into your default branch. Mirage notices the reviewed workflow and activates investigations automatically when an eligible opportunity and idle capacity are available.

The workflow has a manual dispatch trigger for Mirage to call; you do not need to click Run workflow, and do not rerun a failed investigator in GitHub. Fix its setup and use Mirage's resume control instead. Do not make the investigator a required check or add checkout steps, custom actions, caches, artifacts or hooks to it. Mirage verifies its exact contents before dispatching.

Changing the coding client, model or daily limit creates a new setup pull request. Review and merge that workflow update before expecting the new configuration to run.

4. Check that it is working

On the repository page, Awaiting setup changes to your daily usage once Mirage finds the expected workflow on the default branch. That indicates the workflow is installed; it does not guarantee an opportunity has already been found or the login has been tested.

An automatic investigation appears in GitHub Actions as Mirage investigator, with a run named Mirage investigation …. Mirage chooses eligible successful push runs, so let your normal CI complete and leave owned Linux capacity idle. A busy account, insufficient resource headroom, unsupported workflow or lack of a promising candidate can leave usage at zero.

After a proposal passes validation, performance trials run separately. A recommendation appears only after passing, repeatable evidence; failed or inconclusive trials do not create an Apply action. Your subscription login's first real run can also reveal plan, model or credential problems that pause investigations.

Review and apply a recommendation

Expand the recommendation's evidence to inspect the tested change, source commit, baseline/candidate timings and measurement exclusions. Workflow recommendations show both elapsed-time and allocated CPU changes. Less CPU allocation does not by itself establish dollar savings, and a resource saving can come with a slowdown.

Select Create pull request, then review and merge it through your normal GitHub process. Mirage does not commit the change directly or merge it for you. If the tested branch has advanced, Mirage requires fresh evidence instead of applying an old result to new code.

Usage and pause controls

The daily cap counts dispatched proposals, including failed and ambiguous launches. Global investigation and trial allowances also apply, so reaching your personal cap is not a guarantee that every proposal will run. The limit resets at midnight UTC.

Quota, login, client, writeback or timeout failures pause subscription investigations. Mirage shows a reason. After fixing it, select Resume automatic investigations; resuming does not reset today's usage. An enabled subscription integration never silently falls back to a billable generator API call.

Disable subscription investigations stops subscription proposal generation and restores ordinary Mirage service discovery when available. Fixed cache recipes remain available. Delete or revoke the repository's provider and writer secrets if you are retiring the integration entirely.

Troubleshooting

Full provider output is intentionally absent from investigator logs. Use the status in Mirage and your provider's account controls to diagnose login or quota issues.

Privacy and credentials

Credentials stay in your GitHub secret store and the customer's transient investigator VM. The Mirage dashboard never asks you to paste tokens or upload auth files. The coding model receives redacted configuration categories, timing/resource summaries and abstract prior experience; it receives no customer source, raw logs or patches.

Mirage validates bounded proposals before running trials. Customer code, patches and logs stay private; only abstract aggregate experience can inform another repository's investigation. See Security and privacy for the wider execution model.

Test parallel steps

On the repository page, enable Test parallel steps under Verified improvements. It is off by default and requires repository manager access and configured background discovery. It uses the existing service generator or your configured coding subscription, and shares their investigation limits and Mirage-funded trial allowance.

Mirage can propose one contiguous group of 2–10 supported Cargo or Node run steps within one static Linux x64 job. Checkout, tool setup and dependency installation remain sequential. Step conditions, outputs, services, secrets, matrices, arbitrary actions and existing background/parallel syntax remain outside the trial scope. The candidate wraps the original steps in GitHub's parallel block. It preserves step contents and waits for the group before continuing.

A warmup and two sequential/parallel pairs replay the same commit with the same job resources. Recent trials shows the latest ten attempts from the last 30 days, including running, failed, expired and inconclusive results. Valid comparisons retain slowdowns as well as improvements. These are sandbox workflow replay measurements, not measurements of GitHub queueing or runner provisioning; CPU allocation is not actual utilization or dollar savings. An observed passing trial does not prove every possible input is independent. Review the exact workflows and normal PR checks.

Only verified results meeting the existing repeatability threshold offer Create pull request. The source branch must still match the tested commit. Merge the PR to adopt the change. Disabling testing stops new launches; running trials finish and previous results remain available.