How to Register a GitLab Runner in an EC2 Instance
Tags: gitlab, ec2
Published: 2024-01-26 11:25:18

Setting up a GitLab runner on an Amazon EC2 instance is a key step for anyone looking to streamline their CI/CD pipeline. This guide will walk you through the process. Whether you're new to this or looking to refine your current setup, you'll find the necessary steps and insights here.

**Prerequisites**
Before you begin, make sure you can launch and access an EC2 instance. If you prefer to use AWS Session Manager for access, find detailed instructions [here](https://dev.to/gritcoding/simplified-access-using-aws-session-manager-for-ec2-without-a-pem-file-cop).
Alternatively, you can access your EC2 instance using a key pair from your local machine.

---

**Installing GitLab Runner on an EC2 Instance**
First, access your EC2 instance. The installation commands for the GitLab runner vary based on your operating system. For an Amazon Linux AMI, follow these steps:
```
# Linux x86-64
sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"

sudo chmod +x /usr/local/bin/gitlab-runner

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

```

For installation instructions on other operating systems, refer to:
[Installation GitLab Runner](https://docs.gitlab.com/runner/install/)
[Linux Manual Install](https://docs.gitlab.com/runner/install/linux-manually.html#using-binary-file)


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k46agdphxfrfrx5qg5z7.png)

---

**Creating a Project Runner**
To set up your project runner,

Go to your GitLab project's settings and select `CI/CD`.
In the `Runners` section, find the button to add a new project runner.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xjthtmxu04gmqp2kiqxq.png)

Assign relevant tag names for job execution.
If you wish to restrict the runner to the current project, enable the `Lock to current projects` option.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p323psmtvov5h8sxuql6.png)

With these steps completed, we now have the GitLab Runner URL and token ready for registration! 

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ury03tdq1felffwloajm.png)



---
**Registering the GitLab Runner**
Back on your EC2 instance, execute the following command to register the GitLab runner:
```
sudo gitlab-runner register
```

During the registration process, as shown in the screenshot below, you will be prompted to enter the runner's URL and token.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yay9dsil2b988iw43ypk.png)
For my setup, I named the runner `EC2` and selected `shell` as the executor, which you can learn more about [here](https://docs.gitlab.com/runner/executors/index.html).

After registering the runner, you can verify its configuration by checking the `config.toml` file. This file will contain all the details about your runner, as shown in the screenshot below.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gk774g5rbtnzoxskdv3x.png)

With the runner registered, start it using the following command:
```
sudo gitlab-runner run
```

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yiu8ylah366tk22h6ggo.png)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aocdn9bynnxbrydidu8j.png)
Upon successful registration and execution, you should see a green indicator next to your runner in the GitLab project, confirming that it is active and ready to process jobs.

---
**Testing the Setup**

Now that your GitLab Runner is up and running, it's important to test it to ensure it's functioning as expected.

Create a `.gitlab-ci.yml` file in your project's root directory, ensuring that the tags match those assigned to your runner.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bfjvwlx2pbdixgeor9sd.png)
The `.gitlab-ci.yml` file dictates the behaviour of the runner. When you push changes to your repository, it triggers the jobs specified in this file, based on the rules you set.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bh73y9w9frch5p6z0sj0.png)
After pushing a commit to your repository, check the EC2 instance to see if the job is triggered correctly. Initially, you might encounter a scenario where the job is triggered but fails.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/53dpr5z8uccu3o3mh1bx.png)
For instance, in my case, the job failed initially because the git command was missing.

Troubleshoot the issue based on the error logs. In this example, after identifying the missing git command, install the necessary components on your EC2 instance. In my scenario, I installed git, Node.js, and npm, which resolved the issue.

Once the necessary tools are installed on the EC2 instance, re-trigger the job. You should now see a successful execution, as indicated in the screenshot below.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/doxnlqdgw7koqwzmw6dx.png)


A successful run demonstrates that your GitLab Runner is correctly set up and able to handle CI/CD tasks.