GitLab Runners

# CHAPTER 4

GitLab Runners #

1. Introduction #

2. Learning Objectives #

• Define the function of a GitLab Runner.

• Differentiate between Shared Runners and Specific Runners.

• Understand the concept of Runner "Executors" (e.g., Shell, Docker).

• Register a custom GitLab Runner on a private machine.

• Use Runner Tags to route specific jobs to specific machines.

3. Beginner Explanation #

• A customer places a massive order at the drive-thru (The .gitlab-ci.yml file triggers).

• You, the manager, do not cook the food. You look for an available cook in the kitchen.

• The Cooks are the Runners.

• Shared Runners: These are cooks provided by corporate headquarters. They cook for every franchise. Sometimes there is a line, and you have to wait your turn.

• Specific Runners: You hire your own private cook who works *only* for your specific restaurant. They are instantly available, and you can give them specialized equipment (like a massive deep fryer) that corporate cooks don't have.

4. Shared vs. Specific Runners #

• Shared Runners: Hosted and maintained by GitLab.com. They are perfect for small, open-source projects. However, they use shared computing power. If your enterprise app requires 64GB of RAM to compile, a Shared Runner will crash. Furthermore, you share the IP address with thousands of other users, which is bad for secure firewall configurations.

• Specific Runners: You rent a server from AWS or use a computer in your office, install the open-source GitLab Runner software on it, and link it securely to your GitLab project. You control the RAM, the security, and the software installed on it.

5. Runner Executors (How the Runner Runs) #

1. 1. Shell Executor: The Runner simply opens the standard Linux terminal (Bash) on the server and runs your commands directly on the host machine. (Fast, but messy).

1. 2. Docker Executor: The absolute industry standard. For every single job, the Runner spins up a brand new, isolated Docker container, runs your code inside it, and then instantly destroys the container when finished. This guarantees a perfectly clean environment every single time.

6. Mini Project: Configure a GitLab Runner #

Step-by-Step Walkthrough:

1. 1. Navigate to your project on GitLab.com.

1. 2. Go to Settings -> CI/CD -> expand the Runners section.

1. 3. Under Specific runners, click the New project runner button.

1. 4. Provide a Tag (e.g., my-macbook) and click Create runner.

1. 5. GitLab will display a registration command containing a unique Registration Token.

1. 6. On your local machine (assuming you downloaded the GitLab Runner binary), you run the registration command in your terminal:

   gitlab-runner register --url https://gitlab.com/ --registration-token <YOUR_TOKEN>
   ```
7. The terminal will ask you for an Executor. Type `docker`.
8. *The Result:* Refresh the GitLab Runners page. You will see a green dot next to your newly registered private Runner. It is now listening for jobs!

### 7. Routing Jobs with Tags
If you have multiple Specific Runners (e.g., one Mac for compiling iOS apps, one Linux box for deploying databases), how do you tell GitLab which Runner to use for which job? You use **Tags**.

yaml buildiosapp: stage: build script:

• xcodebuild -project MyApp.xcodeproj

• mac-os-runner # This ensures ONLY the Mac runner picks up this job!

• Never Run Untrusted Code on Shell Executors: If you use a Shell Executor, the CI job runs with the permissions of the gitlab-runner user on the host server. A malicious developer could write a script in the .gitlab-ci.yml file to delete the entire server (rm -rf /). Always use the Docker Executor for isolation and security unless you have a highly specific architectural reason not to.

• The "Pending" Pipeline Trap: You push your code, and the pipeline sits in a blue "Pending" state forever, never starting. 99% of the time, this happens because you added a tags: requirement in your YAML file (e.g., tags: [production-server]`), but no Runner with that exact tag is currently online or assigned to the project. The pipeline is waiting for a worker that doesn't exist.

10. Exercises #

1. 1. What is the fundamental difference between a Shared Runner and a Specific Runner?

1. 2. Explain the security and consistency benefits of using the Docker Executor over the Shell Executor.

11. FAQs #

12. Summary #

13. Next Chapter Recommendation #