Busk: Created page with "https://docs.gitlab.com/runner/executors/custom_examples/lxd/ You need to install the `gitlab-runner` apt package first. Installing the package creates the `gitlab-runne..."

2026-08-01T20:10:13Z

Created page with "https://docs.gitlab.com/runner/executors/custom_examples/lxd/ You need to **install the `gitlab-runner` apt package first**. Installing the package creates the `gitlab-runne..."

New page

https://docs.gitlab.com/runner/executors/custom_examples/lxd/

You need to **install the `gitlab-runner` apt package first**.

Installing the package creates the `gitlab-runner` system user and the `/etc/gitlab-runner/` directory structure where `config.toml` lives.

Here is the step-by-step order of operations to get everything set up correctly:

---

## Step 1: Install the GitLab Runner Package

Run these commands on your host machine to add GitLab's official repository and install the runner:

```bash
# 1. Download and run the official GitLab repository setup script
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 2. Install the gitlab-runner package
sudo apt-get install gitlab-runner

```

---

## Step 2: Create the LXD Executor Scripts

Next, create your wrapper scripts for the custom executor (e.g., in `/opt/gitlab-runner/`).

```bash
# Create directory for custom executor scripts
sudo mkdir -p /opt/gitlab-runner

# Create the prepare, run, and cleanup scripts
sudo touch /opt/gitlab-runner/lxd-prepare.sh
sudo touch /opt/gitlab-runner/lxd-run.sh
sudo touch /opt/gitlab-runner/lxd-cleanup.sh

# Make them executable
sudo chmod +x /opt/gitlab-runner/lxd-*.sh

```

*(Paste the script contents into these files and ensure the LXD TLS certificate generation step you performed earlier is configured under the `gitlab-runner` system user's home directory so it can authenticate against LXD).*

---

## Step 3: Register and Configure `config.toml`

Finally, register the runner with your GitLab instance, which will automatically generate or update `/etc/gitlab-runner/config.toml`.

```bash
# Register the runner (you'll need a registration token from GitLab UI)
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.com/" \
--token "YOUR_RUNNER_AUTHENTICATION_TOKEN" \
--executor "custom" \
--description "lxd-restricted-runner" \
--custom-prepare-exec "/opt/gitlab-runner/lxd-prepare.sh" \
--custom-run-exec "/opt/gitlab-runner/lxd-run.sh" \
--custom-cleanup-exec "/opt/gitlab-runner/lxd-cleanup.sh"

```

Once registered, you can edit `/etc/gitlab-runner/config.toml` directly if you need to fine-tune concurrency limits or execution parameters.

Gitlab runner LXD - Revision history

Busk: Created page with "https://docs.gitlab.com/runner/executors/custom_examples/lxd/ You need to **install the `gitlab-runner` apt package first**. Installing the package creates the `gitlab-runne..."

Busk: Created page with "https://docs.gitlab.com/runner/executors/custom_examples/lxd/ You need to install the `gitlab-runner` apt package first. Installing the package creates the `gitlab-runne..."