GitLab Runner Plan

GitLab Runner is a lightweight, powerful tool used to execute jobs in GitLab CI/CD pipelines. It handles tasks defined in .gitlab-ci.yml configuration files, such as building, testing, and deploying code. The Runner fetches code from the GitLab repository, runs it in a predefined environment, and returns the results to GitLab. For further details, refer to the official GitLab Runner documentation.

Document Overview

This document provides instructions for adding a self-hosted runner to a GitLab project. Self-hosted runners offer flexibility and control by running CI/CD pipelines on machines you manage.

Adding a Self-Hosted Runner to a Repository

1. Navigate to GitLab and select the project you wish to configure.

2. From the left sidebar, go to Settings > CI/CD.
   

3. Scroll down to the Runners section and click Expand.
   
   

4. Under the Project runners section select New project runner to set up a new runner.

5. After selecting New project runner.

   1. In the Tags field, enter some tags to help identify the runner. Here we used macos.

2. Provide a descriptive name for your runner in the Runner Description field under the Configuration section.

3. Follow the prompts to complete the runner creation.

6. After creating the runner, copy the runner's URL and token. Be sure to save the token somewhere secure, as you will not be able to retrieve it again.

Setting Up your Agent on MacinCloud

1. Log in to the MacinCloud Portal.

2. From the dashboard, navigate to Agents > Gitlab 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:

   • Description: Match this with the runner description from GitLab.

   • Host Type:

     • Choose GitLab.com Instance if using GitLab.com.

     • Choose Self-hosted Instance if managing your own GitLab server.

   • Instance URL:

     • For GitLab-managed runners, use https://gitlab.com (already filled in).

     • For self-hosted GitLab instances, enter the appropriate URL (e.g., https://gitlab.example.com).

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

   • Access Token: Enter the token generated in GitLab earlier.

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. In GitLab, navigate to your project and go to Settings > CI/CD.
   
   
   

2. Scroll down to the Runners section and click Expand.
   

3. 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. Invalid Instance URL: Ensure the instance URL is entered correctly and update the agent accordingly.

2. Access Token Not Found: Verify that the access token has been entered correctly and update the agent.

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

Steps to Resolve Invalid Instance Errors:

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

2. Verify the Host Type and ensure the correct instance (GitLab.com or self-hosted) is selected.                                     
   
   

3. Ensure the Instance URL is entered correctly.                                                                                                               
   

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

5. 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 Token Not Found Errors:

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

2. Verify that the Access Token is entered correctly and matches the one provided by GitLab 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.