GitHub Actions Runner Plan

GitHub Runner is a lightweight, powerful tool used to execute jobs in GitHub Actions workflows. It handles tasks defined in workflow configuration files (YAML format), such as building, testing, and deploying code. The Runner fetches code from the GitHub repository, runs it in a predefined environment, and returns the results to GitHub. For more information, refer to the official GitHub Runner documentation.

Document Overview 

This document provides step-by-step instructions for adding a self-hosted runner to a GitHub repository. Self-hosted runners are used to execute workflows on machines that you manage, allowing for greater control and customization compared to GitHub-hosted runners.

Adding a Self-Hosted Runner to a Repository

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

3. In the left sidebar, click Actions, then click Runners. 
   
   

4. Click New self-hosted runner.
   

5. Select the operating system and architecture of your self-hosted runner machine based on the subscription you purchased. For example, if you purchased an agent with an Apple Silicon Mac, choose macOS for the operating system and ARM64 for the architecture.
   
   

6. After creating the runner, be sure to copy the runner's URL and token, and store them somewhere safe.

Adding a Self-Hosted Organizational Runner to an Organization

1. On GitHub, navigate to the main page of your organization.

2. Under your organization, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

3. In the left sidebar, click Actions, then click Runners.
   
   
   

4. Click New runner.

6. Select the operating system and architecture of your self-hosted runner machine based on the subscription you purchased. For example, if you purchased an agent with an Apple Silicon Mac, choose macOS for the operating system and ARM64 for the architecture.

7. After creating the runner, be sure to copy the runner's URL and token, and store them somewhere safe.

Setting Up your Agent on MacinCloud

1. Log in to the MacinCloud Portal.

2. From the dashboard, navigate to Agents > Github Agent.

3. Once selecting your agent you will see a page similar to this.

4. Select the agent under your subscriptions.

   
   

5. Click Actions > Edit Agent and complete the necessary fields:

   • Runner Name: Choose a name for your runner.

   • Runner Group: Confirm your available runner groups under Project Settings > Actions > Runner Groups. If you want to create a new runner group for better control over your self-hosted runners, follow the instructions in the GitHub documentation. Otherwise, you can use the default runner group if available.

   • Repository URL: This should be the repository where you want the agent to be active.

     • For a personal repository (associated with a user account), the URL will look like this:

       • https://github.com/your-username/your-repository

     • For an organization repository, the URL will look like this:

       • https://github.com/your-organization/your-repository

     • For an organizational runner, the URL will look like this:

       • https://github.com/your-organization

   • Version: The latest release version is preselected, but you may choose previous stable releases if necessary.

   • Runner Register Token: Enter the token generated in GitHub earlier when setting up your agent.

6. Once done, click Update and allow up to 2 minutes for the changes to take effect.

7.  When your agent is successfully configured, you should see the following confirmation.

Verifying Your Runners Connection

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

3. In the left sidebar, click Actions, then click Runners.
   
   

4. A green dot next to your runner indicates that it has successfully connected and is ready for jobs.

Troubleshooting your Agent 

If your agent has not been successfully configured, it will enter an error state. Below are common examples and steps to resolve the issues:

1. Could not find any self-hosted runner group: Please verify that the runner group has been entered correctly and update the agent accordingly.

2. Register token not found: Please verify that the register token has been entered correctly and update the agent accordingly.

3. Unable to Find Runner Owner: Please verify that the repository URL has been entered correctly and update the agent accordingly.

These errors typically occur when the repository URL or runner group does not exist or has been incorrectly entered, preventing your GitHub agent from connecting to your GitHub repository. Additionally, if the register token is incorrectly entered or has expired, the runner will fail to be verified.

Steps to Resolve Could Not Find Any Self-Hosted Runner Group Error:

1. Navigate to the runner in the error state and select Actions > Edit Agent.

2. Verify the Runner Group and ensure the correct group is selected. If you haven't created a runner group, the default group should be used. If you have created a custom runner group, make sure it is entered correctly.                                                                                                                                     

3. If any of the information appears incorrect, please replace it with the correct information and select update.

4. If all information appears correct, navigate to the runner in the error state and click Actions > Restart.

• If restarting the agent does not resolve the issue, please contact support.

Steps to Resolve Register Token Not Found Error:

1. Navigate to the runner in the error state and select Actions > Edit Agent.

2. Verify that the Runner Register Token is entered correctly and matches the one provided by GitHub when you created your runner.          

3. If any of the information appears incorrect, please replace it with the correct information and select update.

4. If all information appears correct, navigate to the runner in the error state and click Actions > Restart.

• If restarting the agent does not resolve the issue, please contact support.

Steps to Resolve Unable to Find Runner Owner Error:

1. Navigate to the runner in the error state and select Actions > Edit Agent.

2. Ensure the Repository URL is entered correctly.                                                                                                            

3. If any of the information appears incorrect, please replace it with the correct information and select update.

4. If all information appears correct, navigate to the runner in the error state and click Actions > Restart.

• If restarting the agent does not resolve the issue, please contact support.