Skip to content

GitLab runners, CI/CD variables and webhooks

GitLab CI/CD needs three pieces of infrastructure that an administrator or maintainer usually sets up once: runners that execute the jobs, CI/CD variables that give those jobs configuration and secrets without committing them, and webhooks that tell systems outside GitLab when something happened. Mistakes here are costly in both directions: a runner that is too shared or a variable that is not protected can leak production credentials, while a slow webhook receiver gets disabled and silently stops integrations.

This page covers each piece for an invented OrdersPortal project at gitlab.example.test. Facts were checked against the GitLab and GitLab Runner documentation sources in November 2026 (GitLab 19.x). YAML and shell blocks are fragments for your environment; the webhook verifier was run with Node.js 22.

Topic Use it when
Install and register runners Jobs need your own machines, networks or executors.
CI/CD variables and secrets Jobs need configuration and credentials.
Webhooks External systems must react to GitLab events.

GitLab Runner is the application that picks up jobs from GitLab and runs them with an executor: shell runs commands on the host, docker runs each job in a container (the most common choice), kubernetes runs jobs as pods, and docker-autoscaler or instance scale cloud VMs. GitLab.com provides hosted runners; on Self-Managed, or when jobs need private network access, you install your own on a machine separate from the GitLab server. Runners can be instance runners (shared by all projects), group runners or project runners.

The registration workflow has changed, and the legacy one is being removed. You first create the runner in GitLab: for a project, Settings > CI/CD > Runners > Create project runner, choose tags (or Run untagged jobs), and GitLab shows a runner authentication token that starts with glrt-. You then register the installed runner with that token. The legacy runner registration tokens (--registration-token) are deprecated and scheduled for removal in GitLab 20.0, and the Docker Machine executor is deprecated with the same removal target; plan migrations now.

On Debian or Ubuntu, install from GitLab’s package repository (review the script before running it), then register non-interactively (fragment; the token is a placeholder):

Terminal window
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh
sudo apt install gitlab-runner
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.example.test" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image node:24 \
--description "orders-portal-docker"

The configuration is saved in config.toml (/etc/gitlab-runner/config.toml for a root install). Tags are now set on the runner in the GitLab UI at creation time, and jobs select runners with tags:

integration-tests:
stage: test
tags: [docker, orders-db]
image: node:24
script:
- npm ci
- npm run test:integration

Pitfalls:

  • Shared runners and secrets do not mix. A runner that runs jobs from many projects can expose one project’s files or Docker socket to another. Use project or group runners, and mark runners as protected so they only run jobs on protected branches when they hold deployment credentials.
  • Untagged jobs go anywhere. If a runner accepts untagged jobs, any job without tags can land on it, including jobs from forks in merge request pipelines. Turn off Run untagged jobs on special-purpose runners.
  • The shell executor has no isolation. Every job runs as the gitlab-runner user on the host; use it only for trusted projects.

CI/CD variables pass configuration into jobs as environment variables. Define non-sensitive ones in .gitlab-ci.yml (variables:), and sensitive ones in Settings > CI/CD > Variables at project, group or instance level, so they are never committed. Each UI variable has:

  • Visibility: Visible, Masked (the default since GitLab 18.3), or Masked and hidden (the value can never be viewed again in the UI; added for instance variables in 19.0). Masked values are replaced in job logs; they must be a single line of at least 8 characters.
  • Protect variable: only pipelines on protected branches and protected tags receive it. Use it for anything that can deploy.
  • Environments: limit the variable to an environment scope such as production or review/*.
  • Type: Variable (the value is in the environment variable) or File (the value is written to a temporary file and the variable holds its path), which suits tools like kubectl and the AWS CLI that read credentials from files.
  • Expand variable reference: off by default since GitLab 18.6; leave it off for secrets so $ in a value is not interpreted.
# .gitlab-ci.yml (fragment)
variables:
NODE_ENV: production # non-sensitive, versioned with the code
deploy-production:
stage: deploy
environment: production
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
# DEPLOY_TOKEN: masked, protected, scoped to production (Settings > CI/CD > Variables)
# KUBECONFIG_FILE: File type variable, so the job receives a path
- ./scripts/deploy.sh --kubeconfig "$KUBECONFIG_FILE"

When the same name is defined in several places, the highest precedence wins: policy variables, then manual job and pipeline variables (run pipeline form, schedules, API, ci.variable push option), then project, group (closest subgroup first) and instance variables, then dotenv report variables, then .gitlab-ci.yml variables (job rules:variables, job variables, workflow:rules:variables, top-level variables), and finally predefined variables.

Pitfalls:

  • Masking is not protection. A malicious job can still send a masked value elsewhere, for example with curl. Review every change to .gitlab-ci.yml before it runs, and keep deploy credentials protected so unreviewed branches never receive them.
  • Pipeline variables override project settings. Anyone who can run a pipeline with variables can override lower-precedence values; restrict pipeline variables to Maintainers for sensitive projects.
  • Prefer short-lived credentials. For cloud deployments, ID tokens (OIDC) or an external secrets manager avoid long-lived keys in variables altogether.

A webhook sends an HTTP POST with a JSON payload to your URL when selected events happen in a project or group: push, tag push, merge request, pipeline, job, deployment, issue and others. Create one under Settings > Webhooks > Add new webhook (Maintainer role for projects, Owner for groups): enter the URL, choose triggers, optionally filter push events by branch name, wildcard or regex, and keep SSL verification on.

For authentication, GitLab 19.1 and later offer a signing token (recommended; introduced in 19.0). GitLab then follows the Standard Webhooks specification: every request carries webhook-id and webhook-timestamp headers, plus webhook-signature with one or more space-separated values of the form v1,<base64 HMAC-SHA256>, computed over <webhook-id>.<webhook-timestamp>.<raw body> with the base64-decoded token (after removing its whsec_ prefix). The older secret token is sent in plain text in X-Gitlab-Token and is not recommended for new webhooks.

Save as verify-gitlab.mjs and run node verify-gitlab.mjs with Node.js 22. It simulates a delivery; in production the token comes from the webhook settings page, shown only once:

import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
// Verify the Standard Webhooks signature GitLab 19.1+ sends when a signing token is set.
export function isValidGitLabSignature(signingToken, headers, rawBody) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const received = headers["webhook-signature"] ?? "";
if (!id || !timestamp) return false;
// Reject deliveries older than five minutes to limit replay attacks.
const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;
const key = Buffer.from(signingToken.replace(/^whsec_/, ""), "base64");
const digest = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
const expected = Buffer.from(`v1,${digest}`);
return received.split(" ").some((candidate) => {
const actual = Buffer.from(candidate);
return actual.length === expected.length && timingSafeEqual(actual, expected);
});
}
// Simulate one delivery: in production the token comes from the webhook settings page.
const signingToken = "whsec_" + randomBytes(32).toString("base64");
const body = JSON.stringify({ object_kind: "push", ref: "refs/heads/main", project: { path_with_namespace: "orders/orders-portal" } });
const headers = { "webhook-id": "msg_0001", "webhook-timestamp": String(Math.floor(Date.now() / 1000)) };
const key = Buffer.from(signingToken.slice(6), "base64");
headers["webhook-signature"] = "v1," + createHmac("sha256", key).update(`${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`).digest("base64");
console.log("valid delivery:", isValidGitLabSignature(signingToken, headers, body));
console.log("tampered body: ", isValidGitLabSignature(signingToken, headers, body.replace("main", "release")));
console.log("old timestamp: ", isValidGitLabSignature(signingToken, { ...headers, "webhook-timestamp": "1700000000" }, body));

Output:

valid delivery: true
tampered body: false
old timestamp: false

The five-minute timestamp window is a common precaution from the Standard Webhooks specification, not a GitLab requirement; choose your own tolerance.

Receivers must be fast: respond with 200 or 201 quickly and process the event from a queue. After four consecutive failures GitLab temporarily disables a webhook, and after 40 consecutive failures it is disabled permanently until you test it again from the webhook settings. Recent events on the webhook page shows each request and response for debugging, and Test sends a sample event.

Pitfalls:

  • Verify the raw body. Parsing and re-serializing JSON changes the bytes and every signature check fails.
  • Expect duplicates. Timeouts lead to retries; use webhook-id (or the event’s own IDs) to process each event once.
  • Return 4xx only for real misconfiguration. Error responses count as failures; return 400 or ignore unsupported events rather than 500.
Need Use
Run jobs inside your network or with special tools A project or group runner with the Docker or Kubernetes executor
Credentials for deployment jobs Masked (or masked and hidden), protected, environment-scoped variables, or OIDC
Configuration that is not secret variables: in .gitlab-ci.yml
Notify an external system about events A webhook with a signing token
Trigger another GitLab pipeline Multi-project pipelines (trigger:) rather than webhooks

How does runner registration work in current GitLab versions? You create the runner in GitLab (instance, group or project), which issues a runner authentication token starting with glrt-, then run gitlab-runner register with that token and an executor. Registration tokens are deprecated and scheduled for removal in GitLab 20.0.

What is the difference between a masked and a protected variable? Masked hides the value in job logs. Protected only exposes the variable to pipelines on protected branches and tags. Deployment credentials should be both, and ideally scoped to an environment.

When would you use a File type variable? When a tool expects a file path rather than a value, such as a kubeconfig or a cloud CLI credentials file. GitLab writes the value to a temporary file and puts the path in the variable.

How should a webhook receiver authenticate GitLab requests? Use a signing token and verify the webhook-signature HMAC over id.timestamp.body with a constant-time comparison, reject stale timestamps, and respond quickly with 200 before processing asynchronously.

Senior scenario: a merge request from a contributor’s branch printed a production API key in a job log, even though the variable was masked. What went wrong and how do you fix it? The variable was not protected, so an unprotected branch pipeline received it, and the job transformed the value (for example base64) so masking did not match. Rotate the key immediately, mark deployment variables protected and environment-scoped, restrict who can run pipelines with variables, require review of .gitlab-ci.yml changes through Code Owners, run deployments only on protected runners, and move to OIDC or an external secrets manager so no long-lived key exists.