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
For installation instructions on other operating systems, refer to:
Installation GitLab Runner
Linux Manual Install
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.
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.
With these steps completed, we now have the GitLab Runner URL and token ready for registration!
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.
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.
With the runner registered, start it using the following command:
sudo gitlab-runner run
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.
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.
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.
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.
A successful run demonstrates that your GitLab Runner is correctly set up and able to handle CI/CD tasks.
Top comments (0)