> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peak.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Shadow mode

> Run a copy of your CI on Peak before you move.

## Before you start

Start from a new workspace.
Complete [GitHub setup](/github) and select your repositories.

## Start shadow mode

1. Open [Runners](https://app.peak.inc/).
2. Under Choose how to start, choose Shadow first.
3. Open the Shadow CI on Peak pull request in each repository.
4. Review it and merge it.
5. Check that the repository shows Shadow.

Expect a shadow pull request for each repository you add later.

## Review the shadow pull request

Check that your workflows are unchanged.
Check that the pull request adds only these files.

```text theme={null}
.github/workflows/peak-shadow-*.yml
.github/actions/peak-shadow-*/
```

If your CI runs actionlint, check the Peak labels added to this file.

```text theme={null}
.github/actionlint.yaml
```

Read each list in the pull request.

| List | What to do |
| - | - |
| These read secrets | Check each job. It runs twice, once on GitHub and once on Peak. |
| Runs differently on Peak | Check each change. |
| Skipped | Check why each job is left out. |

To undo before merging, close the pull request and delete its branch.

## Check which jobs are copied

Expect copies of Linux jobs that run on push and pull request events.
Expect jobs on other providers' Linux labels to run on a Peak runner of a matching size.
Expect only the Linux rows of a matrix.

Expect Peak to skip these jobs:

* Windows and macOS jobs.
* Deploy and release jobs.
* Jobs that use an environment with protection rules.
* Reusable workflows from other repositories.
* Jobs whose runner comes from variables, inputs, or another job's outputs.
* Jobs that use a skipped job's outputs or artifacts.
* Workflows that run only on a schedule, by hand, or on other events.

## Check that shadow jobs stay safe

Check these changes in each shadow workflow.

| In the copy | Result |
| - | - |
| Every step continues on error | Shadow checks pass even when a step fails. |
| Names start with Peak shadow / | Shadow checks never count as your required checks. |
| Concurrency groups start with peak-shadow- | Shadow runs never cancel your runs. |
| Token permissions are read-only | The job token can't write to your repository. |
| Cache steps only restore | Shadow runs don't overwrite your caches. |
| Docker and Depot build actions don't push | Your registries get no new images from them. |
| Known deploy, publish, comment, notify, and upload steps are removed | These steps run only in your real CI. |
| Artifacts expire after 1 day | Shadow artifacts don't build up. |

Check each shadow workflow for steps that still publish or deploy.
Read each shadow job's result in its last step.

```text theme={null}
Peak shadow outcome: success
Peak shadow outcome: failure
```

## Read the shadow report

Open [Runners](https://app.peak.inc/).
Choose Shadow report beside a repository.
To see every repository, open the [shadow report](https://app.peak.inc/repositories/shadow).
Choose 7, 14, or 30 days.

| Column | Check |
| - | - |
| Agreement | Share of jobs with the same result on Peak and GitHub. |
| Failed only on Peak | Jobs to fix before you move. |
| Failed only on GitHub | Jobs that failed only on your current runners. |
| Speed on Peak | How much faster or slower jobs run on Peak. |
| Queue | Median wait before a job starts. |
| Coverage | Share of your jobs with a shadow copy. |

Open a failed job's Peak and GitHub links to compare both runs.
As a Member, choose Connect GitHub if asked.

## Move to Peak

1. Choose Move to Peak beside the repository on Runners or in the shadow report.
2. Review the Run CI on Peak pull request.
3. Merge it.

Check that each changed runner keeps its old label in a comment.

```yaml theme={null}
runs-on: peak-ubuntu-24.04-4 # peak: was ubuntu-latest
```

Check that the pull request deletes every shadow file.
Then [check the first run](/quickstart#check-the-first-run).

To go back, choose Back to shadow beside the repository.
Merge the Move CI back to shadow pull request.
Check that it restores your old labels and adds the shadow copy.

## Remove shadow mode

1. Choose Remove shadow beside the repository.
2. Merge the Remove Peak shadow CI pull request.

Check that it deletes only shadow files.
Remove the Peak labels from your actionlint config if you no longer need them.
Remove shadow mode before you [remove the repository](/github#remove-a-repository) from Peak.

## Limits

Merge or close the open Peak pull request before you choose another action.
Expect longer queue times while all your repositories are in shadow mode.
Keep shadow mode as long as you need.
Expect no GitHub-hosted minutes for shadow jobs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.