GitLab Runner: Getting started

Connect your Stackhero GitLab Runner to GitLab.com, Stackhero for GitLab, or your own GitLab server and launch your first pipeline in just a few minutes

👋 Welcome to the Stackhero documentation!

Stackhero offers a straightforward GitLab Runner cloud solution that makes running your GitLab CI/CD jobs efficient and hassle-free. Here’s 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: speed up 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 meet your team’s requirements.

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

With Stackhero, your runner always operates 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 handle multiple concurrent jobs in parallel, making it easy to scale your build throughput.

This guide will help 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 suits your workflow. The plan determines 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 will be 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, including those without tags.

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

The previous registration token method 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-...) obtained in Step 2.
• Number of concurrent jobs you wish to allow.

Once you have saved 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 will trigger 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 as follows:

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

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

Next step

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