GitLab Runner: Getting started

Connect your Stackhero GitLab Runner to GitLab.com, Stackhero for GitLab, or your own GitLab server and run your first pipeline in minutes

👋 Welcome to the Stackhero documentation!

Stackhero provides a straightforward GitLab Runner cloud solution that makes running your GitLab CI/CD jobs efficient and hassle-free. Here is what you can expect:

• Unlimited CI/CD minutes: run your pipelines as often as you need, with no per-minute billing or unexpected charges.
• Multiple concurrent jobs: accelerate your development by running several jobs in parallel.
• The Docker executor with Docker-in-Docker support: easily build and push container images as part of your CI/CD process.
• Works seamlessly with both GitLab.com and self-managed GitLab instances.
• A private, dedicated infrastructure with fast NVMe/SSD storage ensures stable and predictable build performance.
• Available in 🇪🇺 Europe and 🇺🇸 USA regions to suit your team's needs.

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 that executes your GitLab CI/CD jobs. Each time a pipeline runs, the runner picks up each job, runs it inside an isolated Docker container, and reports the results back to GitLab.

With Stackhero, your runner always runs on private, dedicated infrastructure. There are no per-minute charges or usage quotas: your CI/CD minutes are unlimited. Depending on your plan, your runner can process many concurrent jobs at once, so scaling your build throughput is straightforward.

This guide helps you connect your Stackhero runner to GitLab and get your first pipeline running quickly.

Step 1: Create your GitLab Runner on Stackhero

From your Stackhero dashboard, you can create a new GitLab Runner service and select a plan that fits your workflow. The plan sets your available CPU, RAM, and the number of concurrent jobs (matching the GitLab Runner concurrent setting: how many jobs the runner can process in parallel).

Your runner is ready to use in about 2 minutes.

Step 2: Create a runner in GitLab

Your runner connects to GitLab using a runner authentication token. You generate this token in GitLab, and you also choose 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 creating the runner, you can:

• Add tags (such as docker or stackhero) to target this runner from your jobs.
• Allow it to run untagged jobs if you want it to process all jobs, even those without tags.

GitLab will provide a runner authentication token that starts with glrt-. Keep this token secure, as your runner uses it to authenticate with GitLab.

The previous registration token flow is deprecated. Please use the runner authentication token (glrt-...) created when you add the runner, as described above.

You can find more details in the official GitLab runner registration documentation.

Step 3: Connect your runner

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

• GitLab URL: Use https://gitlab.com for GitLab.com, or the URL of your self-managed GitLab instance. (If you are running GitLab on Stackhero, this might be https://git.your-company.com.)
• Runner authentication token (glrt-...) you obtained in Step 2.
• Number of concurrent jobs you want to allow.

After you save your configuration, your runner will connect to GitLab and appear as online on the Runners page where you set it up.

Step 4: Run your first pipeline

Add a .gitlab-ci.yml file at the root of your repository to define your pipeline:

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 triggers a pipeline, and your Stackhero runner executes 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

Your pipelines now run on your dedicated runner, with unlimited build minutes and no usage limits to manage.

Next step

If you want to build and push Docker images from your pipelines, you can continue with Building Docker images.