DEV Community

Grit Coding
Grit Coding

Posted on • Updated on

How to Register a GitLab Runner in an EC2 Instance

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.
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



Enter fullscreen mode Exit fullscreen mode

For installation instructions on other operating systems, refer to:
Installation GitLab Runner
Linux Manual Install

Image description


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

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

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

Image description


Registering the GitLab Runner
Back on your EC2 instance, execute the following command to register the GitLab runner:



sudo gitlab-runner register


Enter fullscreen mode Exit fullscreen mode

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

Image description
For my setup, I named the runner EC2 and selected shell as the executor, which you can learn more about here.

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

With the runner registered, start it using the following command:



sudo gitlab-runner run


Enter fullscreen mode Exit fullscreen mode

Image description

Image description
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
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
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
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

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

Top comments (0)