You can run supported GitHub Actions workflows for iOS on Buildkite without rewriting your workflow files. Buildkite's GitHub Actions Compatibility (buildkite-gha) reads the workflow files in your repository and runs them on Buildkite-hosted macOS agents.
In this guide, you'll create a pipeline, add your secrets, choose an Xcode version, and run an existing iOS workflow that builds your app and runs its unit tests.
A Buildkite organization with hosted macOS agents. Hosted macOS is available on the Pro and Enterprise plans. New sign-ups get a 30-day all-access trial with 3,000 vCPU Mac minutes.
A GitHub repository with an iOS workflow that runs on push. Check the compatibility guide to confirm your workflow uses supported features.
Sign up for free with GitHub or email and create an organization.
Select your repository on the New Pipeline page. Email signups connect GitHub first.
Edit your pipeline name, description, and default branch.
Click Create GitHub Actions pipeline.
Buildkite doesn't copy your GitHub secrets. Add each secret your workflow uses before you run it:
Select the Secrets tab.
Click New secret, then enter the secret's Key and Value.
Click Create secret.
When you create a Buildkite organization, its Default cluster includes Buildkite-hosted macOS queues, so you don't need to set up or manage any Macs. Buildkite picks the queue from each job's runs-on label: macos-latest runs on the macos-medium queue.
Your iOS jobs use the macOS and Xcode versions configured on that queue’s base image. Buildkite’s current macOS 26 (Tahoe) images include Xcode 27 and the iOS 27 simulator runtime, but your queue may select an older Xcode by default.
If your project targets iOS 27, check the Mac hosted-agent image explorer to confirm your image includes Xcode 27 and the iOS 27 runtime. If it doesnt, open the macos-medium queue’s Base image settings.
Go to the Agents tab and open the macos-medium queue.
Select the Base image tab. If your current image doesn't include Xcode 27, select one that does.
Under Xcode version, select 27.
Click Save base image.
Automatically run your workflow by pushing a change that matches its branch and path filters.
To run it manually:
Select your workflow.
Optinal: to change the branch, use a clean checkout, or set environment variables, click Change branch or options. Add environment variables under Options > Environment Variables in KEY=value format.
Click Run workflow.
Watch it run live — logs stream until the job finishes. Confirm in the logs the build used the Xcode version you selected. Once the Buildkite build passes, you can disable the GitHub workflow to avoid duplicate runs.
Move one workflow at a time and leave the rest on GitHub Actions for as long as you need.
To learn how the runtime runs your workflows and which features it supports, see Run GitHub Actions workflows in Buildkite .
When you’re ready for more than one workflow, see Migrate from GitHub Actions.
Contact Buildkite support and we'll help you. Send your workflow file and build logs, with any secrets removed.
Verison note: This guide was checked against buildkite-gha v0.102.5. The plugin uses the latest stable runtime release unless you pin a version. Some behavior may differ between versions.