Skip to main content
Remote builds compile your iOS source code on a dedicated cloud Mac runner managed by Revyl. You don’t need a local Mac or Xcode installed — the entire build happens remotely using the Revyl CLI.
Remote builds are an iOS-only capability. Android remote builds are not yet supported.

​
Who This Is For

Use remote builds when your team needs dedicated iOS simulator build capacity without managing Mac infrastructure. This is especially useful when:
  • Your CI provider cannot supply enough Mac capacity.
  • Your builds need a pinned Xcode/macOS environment.
  • You want Revyl to produce the simulator .app and immediately register it for testing.
  • Your build depends on private package mirrors or artifact stores that require a private network path.
Revyl provisions the runner, keeps it assigned to your organisation, routes jobs to that runner, streams logs, registers the resulting build, and cleans up temporary source archives. Enterprise capacity can be backed by dedicated M4-class Mac hosts when that is part of your plan.

​
Get Access

Remote builds require a dedicated build runner provisioned for your organisation. If you don’t have one yet, book a call to get set up:

Book a Demo

Schedule a call to provision a dedicated iOS build runner for your org.

​
Prerequisites

Before using remote builds, make sure you have:
  • Revyl CLI installed and authenticated — see CLI docs
  • An app registered in Revyl — create one from the Builds page or via the CLI
  • Source code committed to git — git archive at HEAD is used, so only committed files are included
  • A dedicated iOS build runner provisioned for your org — Revyl will confirm runner availability before uploading source
If your build uses only public dependencies, that is usually enough. If your build needs private dependencies, see Private Dependencies.

​
Configuration

Add a build section to your .revyl/config.yaml: 
build:
  platforms:
    ios:
      app_id: "uuid-of-your-app"
      setup: "npm install && cd ios && pod install"
      command: "xcodebuild -workspace ios/App.xcworkspace -scheme App -sdk iphonesimulator -configuration Debug build"
FieldRequiredDescription
app_idYesUUID of your app in Revyl (find it on the Builds page)
commandYesThe xcodebuild command to compile your project
setupNoPre-build setup command (e.g. install dependencies)
If you don’t have a config file, the CLI will auto-detect your Xcode project structure.

​
Command Examples

React Native with CocoaPods: 
build:
  platforms:
    ios:
      app_id: "uuid-of-your-app"
      setup: "npm install && cd ios && pod install"
      command: "xcodebuild -workspace ios/App.xcworkspace -scheme App -sdk iphonesimulator -configuration Debug build"
Xcode project without a workspace: 
build:
  platforms:
    ios:
      app_id: "uuid-of-your-app"
      command: "xcodebuild -project App.xcodeproj -scheme App -sdk iphonesimulator -configuration Debug build"
Swift Package Manager dependencies: 
build:
  platforms:
    ios:
      app_id: "uuid-of-your-app"
      setup: "xcodebuild -resolvePackageDependencies -workspace App.xcworkspace -scheme App"
      command: "xcodebuild -workspace App.xcworkspace -scheme App -sdk iphonesimulator -configuration Debug build"

​
Usage

# Remote build with config
revyl build upload --remote

# Remote build without config (requires --app)
revyl build upload --remote --app <app-name-or-id>

# With explicit scheme override
revyl build upload --remote --app <app-id> --scheme MyScheme

# Clean build (wipes DerivedData cache on the runner)
revyl build upload --remote --app <app-id> --clean
The CLI will:
  1. Check that a build runner is available for your org
  2. Package your committed source via git archive
  3. Upload the archive to Revyl
  4. Trigger the remote build
  5. Stream build logs until completion
  6. Register the resulting .app as a new build version
On success, the new version appears on your Builds page and can be used immediately for testing.

​
Private Dependencies

Many enterprise iOS builds need private package mirrors, artifact stores, Git mirrors, license servers, or internal APIs. Revyl supports these with a dedicated runner plus a private network path.

​
Standard Path: No Private Dependencies

If your dependencies are reachable from the public internet, no extra customer networking is required:
  1. Revyl provisions a dedicated runner for your org.
  2. You configure .revyl/config.yaml.
  3. You run revyl build upload --remote.
  4. Revyl uploads source, builds on the runner, and registers the .app.
If your build dependencies are private, Revyl can route runner traffic through AWS PrivateLink. Traffic path: 
build tools on Revyl runner
  -> local runner proxy
  -> Revyl AWS proxy
  -> Revyl interface VPC endpoint
  -> your VPC endpoint service
  -> your NLB
  -> private dependency
Customer inputs needed:
InputExample
First repo/build targetGitLab job, Xcode workspace/project, scheme
Build commandxcodebuild -workspace ios/App.xcworkspace -scheme App -sdk iphonesimulator -configuration Debug build
Setup commandnpm install && cd ios && pod install
Expected artifactSimulator .app produced under DerivedData
Private dependency listArtifactory, npm mirror, CocoaPods mirror, private Git, license server
AWS regionFor example us-west-2
Endpoint service namecom.amazonaws.vpce.<region>.vpce-svc-...
Ports/protocolsHTTPS 443, SSH 22, registry-specific TCP
DNS nameThe hostname the build tools should use
Credentials/secretsPackage manager tokens, certs, Git credentials
Revyl handles:
  • Dedicated Mac runner provisioning, including M4-class capacity when included in your plan.
  • Ansible-based host setup for required Xcode, simulator, proxy, and dependency configuration.
  • Runner org labels and queue routing.
  • Source upload, log streaming, build registration, and cleanup.
  • Consumer interface endpoint setup after your team authorizes Revyl’s AWS principal.
  • Runner proxy configuration and validation from the Mac host.
You handle:
  • Choosing the first build target.
  • Exposing the private dependency through your endpoint-service pattern.
  • Authorizing Revyl’s AWS principal.
  • Providing dependency DNS/auth details.
  • Confirming whether cross-region PrivateLink is allowed when Revyl and your services are in different AWS regions.
Cloudflare Tunnel can be used as a temporary outbound-only speed path if your team asks for it, but PrivateLink is the usual enterprise path when your security team already has AWS endpoint-service patterns.

​
Optional: Private Access to the Revyl API

The PrivateLink path above is for build dependencies that the Revyl runner must reach. Some teams also require their CI system to call the Revyl API or upload source archives through a private path. Treat that as a separate control-plane setup:
  • Your CI still uses the same Revyl CLI commands.
  • Revyl provides the API endpoint details for the private path.
  • Your networking team confirms DNS, endpoint policy, and allowed VPCs.
  • The build-runner dependency path and the CI-to-Revyl API path can be rolled out independently.

​
Troubleshooting

​
No build runner available

No iOS build runners are available for your organisation.
Your org doesn’t have a build runner provisioned, or it’s temporarily offline. Try again in a few minutes, or book a call to get a runner set up.

​
Private dependency unreachable

Symptoms:
  • npm install, pod install, swift package resolve, or artifact downloads hang or fail.
  • The build log shows DNS failures, TCP timeouts, proxy errors, or package-manager authentication errors.
Check:
  • The endpoint service is approved for Revyl’s AWS principal.
  • The endpoint connection is accepted and healthy.
  • The dependency hostname resolves on the runner through the intended private path.
  • The required port is open from the endpoint service to the NLB target.
  • Package-manager credentials are available to the build.

​
Artifactory, npm, CocoaPods, or SPM auth fails

Remote builds run in a clean runner environment. Make sure your setup command can access the same credentials your CI job uses:
  • npm: .npmrc or environment token.
  • CocoaPods: private specs repo access and Git credentials.
  • Swift Package Manager: Git/token access for private packages.
  • Artifactory: registry URL, token, and certificate configuration.

​
Build timeout

Remote builds have a 30-minute execution timeout. If your build consistently times out:
  • Use --clean sparingly (cold builds are slower)
  • Check if your setup command installs unnecessary dependencies
  • Consider splitting large monorepos into smaller build targets

​
Wrong scheme or missing artifact

If the build exits successfully but no simulator .app is registered:
  • Confirm the scheme builds a simulator app, not only tests or a device-only target.
  • Include -sdk iphonesimulator.
  • Confirm the expected product appears under Xcode DerivedData.
  • Try --scheme <SchemeName> if your config omits the scheme.

​
Uncommitted changes not included

The remote build uses git archive HEAD, which only includes committed files. If your latest changes aren’t reflected in the build, make sure to commit them first.

​
Next Steps

Builds Overview

Manage builds and versions

iOS Simulator Builds

Build locally with Xcode

CI/CD

Automate builds in your pipeline
Need help? Contact [email protected]