GitHub Actions Self-Hosted Runner for iOS CI at MacStadium

By Jeff Vincent|

April 28, 2021

First released in November of last year, GitHub Actions is a highly flexible automation tool that is baked into GitHub. With it, you can automate nearly anything relating to your repository. One such use case is running Xcode CI builds for iOS development.

While there are free build resources available through GitHub Actions, many teams that are executing CI jobs relating to a professional project will prefer to have a greater degree of control over their build environment, which is why we will be standing up a GitHub Actions self-hosted runner in a macOS compute resource hosted by MacStadium.

Networking and Firewall Considerations

Because the self-hosted runner executes long-polling requests against your repository, the runner will only need to be able to access the GitHub API and not vice-versa. This dramatically simplifies setup when it is being stood up behind a firewall, such as those that come standard with Mac VMs running in OrkaVMware, and Anka, and can be added to bare metal resources hosted by MacStadium.

Defining a Workflow

To create a workflow for GitHub Actions to execute, you’ll need to define it as a YAML file in your repository. To do so, navigate to the Actions tab in your repository and click New workflow.

GitHub Actions_New Workflow

When you do so, you will be given the option of choosing a new workflow template that aligns with the code in your repository. If you are working with Swift, for example, the suggested template will be one in which Swift test and build stages are carried out.

However, as we are going to run an xcodebuild command, we will define a simple workflow of our own.

GitHub Actions_Define Workflow

In the above, we have a minimal workflow. Specifically, we have given our workflow a name with the name value. Then we have defined the actions that will cause the workflow to be executed with the on value. This workflow will be executed by either a push or a pull request to the branch main of our project.

And finally, we define the workflow itself with the jobs value. Within this section, we have defined one job, which we have named build. However, it is worth noting that you can define any number of jobs you like here.

Within the job definition, we first need to tell GitHub Actions where the job will be carried out with the runs-on value. By entering self-hosted here, we are telling GitHub Actions to check for any self-hosted runners associated with this repository, and if it finds one it will run the job there.

Next, we define the list of steps to be carried out by the self-hosted runner when it receives the job. The uses: actions/checkout@v2 step is what tells our runner to check out the code from our associated repository. Then, we have a named step Build App where we pass our xcodebuild command.

Set up a Self-Hosted Runner

Navigate to the Settings tab in your repository. Select Actions from the sidebar navigation, and click Add Runner. When you do, you’ll see a view like that shown below. From here, simply open a terminal on your macOS compute resource hosted by MacStadium, and copy and paste each of the commands listed into the terminal. Accept the default values offered in the interactive terminal, and finally execute the script that will be available in your new runner directory.

NOTE: You will need to keep the terminal open for the runner to stay active so that it can receive jobs.

GitHub Actions_Set up a self-hosted runner

Once you’ve run each of the above commands, you should see the output in the terminal that the runner is up and waiting for jobs. You can then navigate in your browser to your GitHub repository, click the Settings tab, and then select Actions again in the sidebar, where you should see your newly associated runner with a green dot and a status of Idle, as shown below.

GitHub Actions_Idle Status

Execute your new workflow

Finally, to execute your new workflow, simply commit a change to your repository. When you do, you’ll see the job execute in the terminal you’ve left open on your macOS compute resource. You will also be able to see the status of the job by navigating to the Actions tab in your repository. To view logs from the job, simply double-click on the workflow run you would like to inspect.

GitHub Actions_Execute New Workflow


GitHub Actions is an automation tool that is free to use with any GitHub account. It offers the ability to stand up your own self-hosted runner for teams that need a secure way to run CI jobs for professional projects. Above, we have demonstrated the process by which you can use GitHub Actions to run secure iOS CI jobs with Xcode on macOS compute resources hosted by MacStadium.

Share this article


Orka, Orka Workspace and Orka Pulse are trademarks of MacStadium, Inc. Apple, Mac, Mac mini, Mac Pro, Mac Studio, and macOS are trademarks of Apple Inc. The names and logos of third-party products and companies shown on the website are the property of their respective owners and may also be trademarked.

©2023 MacStadium, Inc. is a U.S. corporation headquartered at 3525 Piedmont Road, NE, Building 7, Suite 700, Atlanta, GA 30305. MacStadium, Ltd. is registered in Ireland, company no. 562354.