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 offers a ready-to-use GitLab Runner cloud solution that runs your GitLab CI/CD jobs, with benefits including:

• Unlimited CI/CD minutes: no per-minute billing, run your pipelines around the clock.
• Dozens of concurrent jobs so a whole pipeline stage runs at once.
• The Docker executor with Docker-in-Docker support to build and push your images.
• Works with GitLab.com and any self-managed GitLab.
• A private and dedicated VM with NVMe/SSD disks for fast, consistent builds.
• Available in 🇪🇺 Europe and 🇺🇸 USA.

Save time: it only takes a few minutes to connect your first GitLab Runner and start running pipelines!

Introduction

A GitLab Runner is the agent that runs your GitLab CI/CD jobs. Every time a pipeline starts, the runner picks up each job, runs it inside a clean Docker container, and reports the result back to GitLab.

On Stackhero, your runner lives on a private, dedicated VM. There is no per-minute billing and no quota: your CI/CD minutes are unlimited, and your runner can execute dozens of concurrent jobs depending on your plan.

This guide connects your Stackhero runner to your GitLab in a few minutes.

Step 1: Create your GitLab Runner on Stackhero

In your Stackhero dashboard, create a new GitLab Runner service and pick the plan that fits your needs. The plan defines the CPU, RAM, and the number of concurrent jobs (this maps to the GitLab Runner concurrent setting: the number of jobs your runner runs at the same time).

Your runner starts in about 2 minutes.

Step 2: Create a runner in GitLab

Your runner connects to GitLab using a runner authentication token. You create it in GitLab, where you also decide the scope of the runner:

• 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 (self-managed GitLab only): go to the Admin area > CI/CD > Runners > New instance runner.

When creating the runner, you can:

• add tags (for example docker, stackhero) to target this runner from your jobs,
• allow it to run untagged jobs if you want it to pick up every job.

GitLab then gives you a runner authentication token that starts with glrt-. Keep it safe: it is the credential your runner uses to connect.

The old registration token flow is deprecated. Use the runner authentication token (glrt-...) created together with the runner, as described above.

Step 3: Connect your runner

Back in your Stackhero dashboard, open your GitLab Runner service configuration and provide:

• your GitLab URL: https://gitlab.com for GitLab.com, or the URL of your self-managed GitLab (for example a GitLab hosted on Stackhero, like https://git.your-company.com),
• the runner authentication token (glrt-...) from Step 2,
• the number of concurrent jobs you want to allow.

Save your configuration. Your runner connects to GitLab on its own and appears as online in the Runners page where you created it.

Step 4: Run your first pipeline

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. GitLab starts a pipeline and your Stackhero runner executes the jobs. If you added tags when creating the runner, target them from your jobs:

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

That's it: your pipelines now run 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.