---
title: "Cómo instalar y registrar GitLab Runner en Ubuntu 24.04"
description: "Instala GitLab Runner desde el repositorio oficial en Ubuntu 24.04, regístralo con un token de autenticación y ejecuta tu primer job con el executor Docker."
category: "CI/CD DevOps"
language: es
source: https://cubepath.com/es/docs/ci-cd-devops/instalacion-y-configuracion-de-gitlab-runner
updated: 2026-09-25
---

# Cómo instalar y registrar GitLab Runner en Ubuntu 24.04

GitLab Runner es el agente que ejecuta los jobs definidos en `.gitlab-ci.yml`. Tener un runner propio te da control sobre el hardware, la caché y las herramientas disponibles, y no consume los minutos de cómputo de GitLab.com. En este tutorial instalarás GitLab Runner en Ubuntu 24.04 desde el repositorio oficial, lo registrarás con el executor Docker, ajustarás la concurrencia y comprobarás que ejecuta un pipeline real.

## Requisitos previos

Para seguir esta guía necesitas:

- Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 2 GB de RAM y 20 GB libres en disco para imágenes y caché.
- Un usuario no root con privilegios `sudo`.
- Docker Engine instalado desde el repositorio oficial de Docker (el executor Docker lo necesita).
- Un proyecto en GitLab.com o en tu propia instancia de GitLab, con rol **Maintainer** u **Owner** para crear runners.

El runner solo abre conexiones salientes hacia GitLab por HTTPS, así que no necesitas abrir puertos de entrada en el firewall.

## Paso 1: Instalar GitLab Runner

GitLab publica un script que añade su repositorio APT y la clave de firma. Descárgalo primero para poder revisarlo antes de ejecutarlo:

```bash
curl -fsSL -o gitlab-runner-repo.sh https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh
less gitlab-runner-repo.sh
```

Ejecútalo e instala el paquete:

```bash
sudo bash gitlab-runner-repo.sh
sudo apt install gitlab-runner
```

El paquete crea el usuario de sistema `gitlab-runner` y el servicio `gitlab-runner`, que queda habilitado y en marcha. Compruébalo:

```bash
gitlab-runner --version
sudo systemctl status gitlab-runner --no-pager
```

```output
Version:      18.x.x
...
● gitlab-runner.service - GitLab Runner
     Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; preset: enabled)
     Active: active (running)
```

## Paso 2: Crear el runner en GitLab

Desde GitLab 16 los runners se crean primero en la interfaz, que genera un token de autenticación (empieza por `glrt-`). Los antiguos tokens de registro están obsoletos.

1. En tu proyecto, ve a **Settings > CI/CD** y despliega **Runners**.
2. Pulsa **New project runner** (en algunas versiones, **Create project runner**).
3. En **Tags** escribe `docker,linux`. Deja **Run untagged jobs** desmarcado si quieres que el runner solo acepte jobs con esas etiquetas.
4. Opcionalmente añade una descripción y un **Maximum job timeout**.
5. Pulsa **Create runner**.

GitLab muestra el token `glrt-...` una sola vez. Cópialo; lo usarás en el siguiente paso.

> Nota: si administras una instancia propia, también puedes crear runners de grupo (**Build > Runners** en el grupo) o de instancia (**Admin > CI/CD > Runners**) con el mismo procedimiento.

## Paso 3: Registrar el runner con el executor Docker

El executor Docker ejecuta cada job en un contenedor limpio a partir de la imagen indicada en `.gitlab-ci.yml`, lo que evita que los jobs se contaminen entre sí. Registra el runner sustituyendo `your_runner_token` por el token del paso anterior. Si usas una instancia propia, cambia también la URL:

```bash
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "your_runner_token" \
  --name "ci-runner-01" \
  --executor "docker" \
  --docker-image "alpine:latest"
```

`--name` es el nombre local del runner en `config.toml` y `--docker-image` es la imagen por defecto para jobs que no declaran `image:`. Las etiquetas, la descripción y el tiempo máximo ya se definieron en la interfaz.

```output
Runtime platform                                    arch=amd64 os=linux ...
Verifying runner... is valid                        runner=AbCdEf12
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
```

Comprueba que el runner está registrado y que GitLab lo acepta:

```bash
sudo gitlab-runner list
sudo gitlab-runner verify
```

En GitLab, en **Settings > CI/CD > Runners**, el runner aparece con un punto verde (**Online**) al cabo de unos segundos.

## Paso 4: Ajustar config.toml

El registro escribe la configuración en `/etc/gitlab-runner/config.toml`. Ábrelo:

```bash
sudo nano /etc/gitlab-runner/config.toml
```

Verás algo parecido a esto. Los cambios más útiles son `concurrent` (cuántos jobs puede ejecutar el servicio a la vez, por defecto 1) y los límites de recursos de los contenedores:

```toml
concurrent = 4
check_interval = 0

[[runners]]
  name = "ci-runner-01"
  url = "https://gitlab.com"
  token = "glrt-..."
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    pull_policy = ["if-not-present"]
    memory = "2g"
    cpus = "1.5"
    volumes = ["/cache"]
    shm_size = 0
```

- `concurrent = 4`: hasta cuatro jobs en paralelo. Ajústalo a los núcleos y la RAM del servidor.
- `pull_policy = ["if-not-present"]`: reutiliza imágenes ya descargadas, lo que acelera mucho los jobs. Usa `always` si necesitas garantizar siempre la última versión de una etiqueta.
- `memory` y `cpus`: límites por contenedor de job, para que un job descontrolado no tumbe el servidor.
- `volumes = ["/cache"]`: volumen donde el runner guarda la caché definida con `cache:` en los jobs.

GitLab Runner detecta los cambios en `config.toml` y los recarga solo, pero reiniciar el servicio confirma que el archivo es válido:

```bash
sudo systemctl restart gitlab-runner
sudo journalctl -u gitlab-runner -n 20 --no-pager
```

Si hay un error de sintaxis, aparecerá en el log.

## Paso 5: Ejecutar un pipeline de prueba

Crea o edita `.gitlab-ci.yml` en la raíz del proyecto. Las `tags` hacen que GitLab envíe los jobs a tu runner:

```yaml
stages:
  - test

default:
  tags:
    - docker

check-runner:
  stage: test
  image: python:3.12-slim
  script:
    - python --version
    - echo "Ejecutado en $CI_RUNNER_DESCRIPTION"
  cache:
    key: "$CI_COMMIT_REF_SLUG"
    paths:
      - .cache/pip
```

Haz commit y push. En **Build > Pipelines** abre el job; el log debe empezar indicando tu runner y el executor:

```output
Running with gitlab-runner 18.x.x (...)
  on ci-runner-01 AbCdEf12, system ID: s_...
Preparing the "docker" executor
Using Docker executor with image python:3.12-slim ...
...
$ python --version
Python 3.12.x
Job succeeded
```

En el servidor puedes seguir la actividad del runner en tiempo real:

```bash
sudo journalctl -u gitlab-runner -f
```

## Paso 6: Construir imágenes Docker desde los jobs (opcional)

Para ejecutar `docker build` dentro de un job hay que usar Docker-in-Docker, que necesita contenedores privilegiados. Actívalo solo en runners dedicados a proyectos de confianza, porque un job privilegiado puede tomar el control del servidor.

En `/etc/gitlab-runner/config.toml`, dentro de `[runners.docker]`, cambia `privileged` y añade el volumen de certificados:

```toml
    privileged = true
    volumes = ["/certs/client", "/cache"]
```

Reinicia el servicio:

```bash
sudo systemctl restart gitlab-runner
```

Un job que construye y publica en el registro de contenedores de GitLab queda así:

```yaml
build-image:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  tags:
    - docker
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
```

Recuerda añadir `build` a la lista `stages` del archivo.

## Alternativa: executor shell

Si prefieres que los jobs se ejecuten directamente en el servidor, con las herramientas instaladas en el sistema, registra el runner con `--executor "shell"` y sin `--docker-image`. Los jobs se ejecutan como el usuario `gitlab-runner`, en su directorio `/home/gitlab-runner`. Es más rápido, pero los jobs comparten estado y cualquier job puede leer lo que dejaron los anteriores.

## Mantenimiento

Actualiza el runner junto con el resto del sistema; el servicio se reinicia solo tras la actualización:

```bash
sudo apt update && sudo apt install --only-upgrade gitlab-runner
```

El executor Docker acumula imágenes y volúmenes de caché. Revisa el espacio con `docker system df` y limpia periódicamente lo que no se usa:

```bash
sudo docker system prune --filter "until=168h"
```

Para retirar un runner, bórralo en GitLab (**Settings > CI/CD > Runners**) y elimina su entrada local:

```bash
sudo gitlab-runner unregister --name ci-runner-01
```

Haz copia de `/etc/gitlab-runner/config.toml`: contiene los tokens y toda la configuración del runner.

## Solución de problemas

**El job se queda en `pending` con el mensaje "This job is stuck"**: ningún runner online tiene todas las etiquetas del job. Comprueba que las `tags` del job coinciden con las del runner, o marca **Run untagged jobs** en el runner.

**`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`**: Docker no está instalado o no está en marcha. Comprueba con `sudo systemctl status docker`.

**Con executor shell: `ERROR: Job failed: prepare environment: exit status 1`**: en Ubuntu, el archivo `/home/gitlab-runner/.bash_logout` limpia la consola y rompe la preparación del job. Elimínalo con `sudo rm /home/gitlab-runner/.bash_logout`.

**Jobs Docker-in-Docker fallan con `error during connect`**: falta `privileged = true`, el volumen `/certs/client` o la variable `DOCKER_TLS_CERTDIR` en el job.

## Conclusión

Tienes un GitLab Runner propio en Ubuntu 24.04, registrado con un token de autenticación, ejecutando cada job en un contenedor aislado con límites de CPU y memoria y caché local. Como siguientes pasos, puedes añadir más runners con etiquetas distintas para separar cargas, construir imágenes con Docker-in-Docker en un runner dedicado o añadir análisis de calidad con SonarQube a tus pipelines.