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.
Topics on this page
Section titled “Topics on this page”| 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. |
Install and register runners
Section titled “Install and register runners”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):
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.shless script.deb.shsudo bash script.deb.shsudo 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:integrationPitfalls:
- 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
tagscan land on it, including jobs from forks in merge request pipelines. Turn off Run untagged jobs on special-purpose runners. - The
shellexecutor has no isolation. Every job runs as thegitlab-runneruser on the host; use it only for trusted projects.
Variables and secrets
Section titled “Variables and secrets”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
productionorreview/*. - Type:
Variable(the value is in the environment variable) orFile(the value is written to a temporary file and the variable holds its path), which suits tools likekubectland 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.ymlbefore 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.
Webhooks
Section titled “Webhooks”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: truetampered body: falseold timestamp: falseThe 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
400or ignore unsupported events rather than500.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- GitLab administration guides
- GitLab CI/CD keywords and usage:
tags,rules,environmentandvariablesin detail. - GitLab build pipeline and deploy pipeline
- GitHub Actions and automation: the GitHub equivalents.