GitLab Runner: Getting started

Connect your Stackhero GitLab Runner to GitLab.com or a self-hosted GitLab and run your first pipeline

👋 Welcome to the Stackhero documentation!

Stackhero offers you an easy-to-use GitLab Runner cloud solution, designed to efficiently run your GitLab CI/CD jobs. Here’s what you can expect:

Unlimited CI/CD minutes: there’s no per-minute billing, so your pipelines can run whenever you need them.

Concurrent jobs: run multiple jobs in parallel to speed up your entire pipeline.

The Docker executor with Docker-in-Docker support: simplify building and pushing your container images.

Compatible with GitLab.com as well as any self-managed GitLab instance.

A private, dedicated VM powered by fast NVMe/SSD disks for consistent, reliable builds.

Available in both 🇪🇺 Europe and 🇺🇸 USA regions.

Save time: connect your first GitLab Runner and start running pipelines in just a few minutes!

Introduction

A GitLab Runner is the agent responsible for executing your GitLab CI/CD jobs. Each time a pipeline is triggered, the runner picks up each job, runs it inside a clean Docker container, and then sends the results back to GitLab.

With Stackhero, your runner operates on a private, dedicated VM. There are no per-minute fees or usage quotas, and your CI/CD minutes are unlimited. Depending on your plan, your runner can handle dozens of concurrent jobs at the same time.

This guide will show you how to connect your Stackhero runner to GitLab in just a few minutes.

Step 1: Create your GitLab Runner on Stackhero

From your Stackhero dashboard, you can create a new GitLab Runner service and select the plan that best fits your needs. The plan determines your available CPU, RAM, and the number of concurrent jobs (which corresponds to the GitLab Runner concurrent setting, i.e., the number of jobs that can run in parallel).

Your runner will be up and running in about 2 minutes.

Step 2: Create a runner in GitLab

Your runner connects to GitLab using a runner authentication token. You will generate this token in GitLab, where you also define the runner's scope:

Project runner: Open your project, then go to Settings > CI/CD > Runners > New project runner.
Group runner: Open your group, then go to Settings > CI/CD > Runners > New group runner.
Instance runner (for self-hosted GitLab only): Go to the Admin area > CI/CD > Runners > New instance runner.

When creating the runner, you can:

Add tags (such as docker or stackhero) to help you target this runner from your jobs.
Allow it to run untagged jobs if you want it to pick up all jobs.

GitLab will provide you with a runner authentication token that starts with glrt-. Be sure to keep this token secure, as it is used by your runner to authenticate.

The old registration token method is deprecated. Please use the runner authentication token (glrt-...) created alongside the runner, as described above.

Step 3: Connect your runner

Go back to your Stackhero dashboard, open your GitLab Runner service configuration, and enter the following information:

Your GitLab URL: Use https://gitlab.com for GitLab.com, or the URL of your self-hosted GitLab instance (for example, if you are running GitLab on Stackhero, this could be https://git.your-company.com).
The runner authentication token (glrt-...) you obtained in Step 2.
The number of concurrent jobs you want to allow.

Once you save your configuration, your runner will automatically connect to GitLab and appear as online on the Runners page where you created it.

Step 4: Run your first pipeline

To get started, add a .gitlab-ci.yml file at the root of your repository:

stages:
  - build
  - test

build:
  stage: build
  image: node:22
  script:
    - npm ci
    - npm run build

test:
  stage: test
  image: node:22
  script:
    - npm test

Commit and push your changes. GitLab will start a pipeline, and your Stackhero runner will execute the jobs. If you added tags when creating the runner, you can target them in your jobs like this:

build:
  stage: build
  tags:
    - stackhero
  image: node:22
  script:
    - npm ci
    - npm run build

That's it. Your pipelines are now running on your own dedicated runner, with unlimited build minutes.

Next step

Want to build and push Docker images from your pipelines? Continue with Building Docker images.