Skip to main content

​
Before you start

Complete GitHub setup. Check that your target runner matches the job’s architecture. Keep Windows and macOS jobs on their existing runners.

​
Use terminal setup

Use terminal setup for fixed Ubuntu labels, Linux label lists, and simple OS matrices. Review the skipped-job notes for expressions and matrices with include or exclude entries. For a mixed OS matrix, check that only the matching Ubuntu entries change. Keep the matrix expression on the job.

​
Use Peak agent setup

Use the wizard for jobs that terminal setup leaves for manual review.
Review the listed workflow files before you agree to upload them. Expect to send only the workflow files that need extra planning. Limit each file to 64 KiB and each request to 20 files. Remove any hardcoded secrets before you send a workflow. Review the returned diff. Check runner labels and matrix values. For include-only matrices, keep each row’s architecture and other job fields. Keep your steps, commands, permissions, and triggers unchanged. Read the notes for any jobs that still need manual changes. To use the local plan without uploads, disable the agent.
To preview without uploads or a new branch, use a dry run.
If agent planning fails, read the error and review the local plan before proceeding.

​
Start without GitHub Actions

Review the starter workflow if your repository has no GitHub Actions workflow. Fill in any missing build or test commands. If you use another CI system, keep its configuration until your new workflow passes. Port any missing jobs yourself. Do not expect setup to convert CircleCI, GitLab, Buildkite, Jenkins, Travis, Azure, or Bitbucket pipelines.

​
Preview one job

Sign in to the CLI. List the released runner types.
Choose a label from the result. If the list is empty, wait for a released runner type before using this preview. Replace the example label below with your chosen label.
Use this preview for one fixed, single-line Ubuntu or Depot Ubuntu runner label. Use terminal or agent setup for runner lists and matrices. Keep the workflow file under 128 KiB. Review the returned workflow before you apply the edit yourself. Check runner availability separately before you merge.