GitLab Runner: Getting started

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

👋 Welcome to the Stackhero documentation!

Stackhero gives you an easy-to-use GitLab Runner cloud solution designed to handle your GitLab CI/CD jobs efficiently. Here is what you can look forward to:

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

Multiple concurrent jobs: run several jobs at the same time to speed up your entire pipeline.

The Docker executor with Docker-in-Docker support: streamline 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: you can connect your first GitLab Runner and start running pipelines in just a few minutes!

Introduction

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

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

This guide walks you through connecting 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 choose the plan that matches your needs. The plan determines your available CPU, RAM, and the number of concurrent jobs (which corresponds to the GitLab Runner concurrent setting, the number of jobs that can run simultaneously).

Your runner will be up and running in around 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 decide 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-managed GitLab only): Go to the Admin area > CI/CD > Runners > New instance runner.

When you create the runner, you can:

Add tags (like 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 every job.

GitLab will provide a runner authentication token that starts with glrt-. Make sure to keep this token secure, as it is what your runner uses to authenticate.

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

Step 3: Connect your runner

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

Your GitLab URL: Use https://gitlab.com for GitLab.com, or the URL of your self-managed GitLab instance (for example, if you are running GitLab on Stackhero, this might be https://git.your-company.com).
The runner authentication token (glrt-...) you obtained in Step 2.
The number of concurrent jobs you would like 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 may want to target them in your jobs like this:

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

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

Next step

Interested in building and pushing Docker images from your pipelines? You can continue with Building Docker images.