Integrations
Revyl Mac CI with GitHub Actions
Run a GitHub Actions job on a Revyl Mac and keep the desktop evidence in Revyl.
runs-on: revyl-macos gives one GitHub Actions job a Revyl Mac computer. Your workflow runs on that Mac, so the job can use Xcode, the iOS Simulator, xcrun simctl, and the Revyl CLI without managing a Mac runner yourself.
This is early access and available on request. The Revyl GitHub App receives the workflow_job events this runner needs, but your installation must have the runner and Actions permissions accepted and your Revyl organization must be enabled for Mac computers. Ask Revyl to enable the runner for your organization; there is no promised enablement date.
Set up with an agent
Paste one prompt and your coding agent does the rest.
Setup prompt
Run one private GitHub Actions job on a Revyl Mac. Read https://docs.revyl.com/integrations/github-actions-macos.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl. Ask Revyl to enable Mac CI for this GitHub App installation, then add a job with exactly `runs-on: revyl-macos`. Start with the first-job cookbook and keep the job below the computer's one-hour compatibility limit. You're done when the job completes and its GitHub Actions computer session appears in Revyl. Ask me before anything that needs my login or approval.
Before you start
Revyl admits a job only when all of these conditions hold:
- The job uses exactly the single label
revyl-macos. Labels are matched case-insensitively, but a label list such as[self-hosted, revyl-macos]is not accepted. - The repository is private, belongs to an organization, and is covered by the Revyl GitHub App installation.
- The installation can deliver
workflow_jobevents and manage the organization's self-hosted runner group. If GitHub asks an organization owner to accept updated App permissions, do that before retrying the job. - The Revyl organization has Mac computers enabled.
Public repositories are refused. Fork-triggered pull request jobs also do not receive repository secrets, so keep secret-dependent steps out of untrusted fork workflows.
The Mac in the job
The sealed guest includes:
- Xcode and an iOS Simulator runtime.
xcrun simctlfor creating, booting, installing, and launching Simulator apps.- The Revyl CLI at
/opt/revyl/bin/revyl, also available asrevylon the login shellPATH. - A
REVYL_COMPUTER_IDenvironment variable identifying the computer that owns the job.
The job account cannot use passwordless sudo, and the preinstalled Homebrew tree is not writable by the job account. Install additional tools under $HOME instead. Plan for a one-hour computer lifetime across the current Mac host pool, and set a GitHub Actions timeout that leaves room for cleanup. The runner does not shorten or extend the computer; the computer's host and backend lifetime compatibility decide it.
The runner does not currently inject a job-scoped REVYL_API_KEY. If a workflow calls Revyl, pass your own repository or organization secret. Never print the key or the computer ID.
What Revyl records
The Mac computer page keeps the activity from the job and the whole desktop recording when one is saved. The Simulator is part of that desktop recording when its window is visible; Revyl does not crop the recording to a single app window.
The Sessions list shows the run as GitHub Actions. When GitHub provides pull request or branch metadata, the row shows the pull request or branch and links back to the GitHub Actions run. From a workflow step, revyl computer report "$REVYL_COMPUTER_ID" --format json reads the computer report. The final recording can finish uploading after the job has exited, so read it from the computer page after the computer stops.
Choose a cookbook
- First job: prove the runner, CLI, and computer identity with no checkout or secret.
- Build an iOS app in Simulator: build an
.app, boot a Simulator, install it, and launch it. - Run existing Maestro iOS flows: install Java and Maestro under
$HOME, then keep themaestro testcommand unchanged. - Use the Revyl CLI: run the preinstalled CLI and read the computer report with your own secret.
- Install tools without
sudo: put a user-local Node CLI under$HOME.
Verify's currentComputer() and current_computer() attachment helpers are in the next Verify release, not the published package today. This guide does not present them as installable yet.
Common failures
The job stays queued
Check the label first. runs-on: [self-hosted, revyl-macos] is a different label set and is refused. Then check that the repository is private, the Revyl GitHub App covers it, its runner permissions are accepted, and the Revyl organization has Mac computers enabled.
GitHub says the runner group is unavailable
An organization owner needs to accept the Revyl App's self-hosted runner and Actions permissions. Revyl manages the runner group; do not create a second customer runner group for this job.
A command asks for sudo
The job account cannot elevate. Use a user-local install under $HOME, or move the dependency into the workflow's build artifact rather than changing the Mac image.
A Revyl CLI command says authentication is missing
The runner identity and REVYL_API_KEY are separate. The runner always provides REVYL_COMPUTER_ID; a workflow that calls the Revyl API must provide its own REVYL_API_KEY secret. Fork-triggered jobs do not receive that secret.
The recording is not ready when the job ends
The computer report and desktop recording are finalized by the computer owner after the job stops. Open the computer page again after the workflow completes instead of treating the last shell step as the recording upload boundary.