GitLab Runner TUI is a read-only terminal dashboard for inspecting GitLab runners and their managers. Use the interactive dashboard for day-to-day checks, or run one-shot commands that return JSON for scripts and continuous integration (CI) jobs.

• Runner status, type, version, tags, and pause state
• Manager status, version, system ID, and last contact time
• Fleet health and runners with no online manager
• Stale runners that have stopped contacting GitLab
• Runners with no managers
• Runners with overlapping managers during rotation
• Query timing and GitLab API request counts in command output

The application only reads runner data from GitLab. It does not register, pause, delete, or edit runners.

If Docker is installed, open the dashboard without a GitLab account or token:

docker run --rm -it ghcr.io/damacus/gitlab-runner-tui:latest --demo

The demo uses built-in fixture data and does not make network requests.

GitHub Releases provides these archives:

Download the matching archive and checksums-sha256.txt. Then extract the binary and put it on your PATH. For example, on Linux x86-64:

tar -xzf gitlab-runner-tui-linux-amd64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 gitlab-runner-tui "$HOME/.local/bin/gitlab-runner-tui"
gitlab-runner-tui --help

If $HOME/.local/bin is not on your PATH, add it to your shell configuration or install the binary in another directory that is on your PATH.

The published image supports Linux on AMD64 and ARM64:

docker pull ghcr.io/damacus/gitlab-runner-tui:latest

The latest tag follows the newest release. Use a full version tag for a repeatable deployment.

The repository uses mise to install the pinned Rust toolchain and build tools:

git clone https://github.com/damacus/gitlab-runner-tui.git
cd gitlab-runner-tui
mise trust
mise install
mise run build:release

The binary is written to target/release/gitlab-runner-tui.

For GitLab 17.1 and later, start with a personal access token that has:

read_api, manage_runner

Add read_user if GitLab rejects the initial user validation request. GitLab versions older than 17.1 can use the broader api scope.

Your GitLab role must also permit access to the runners you want to inspect. See GitLab token permissions for endpoint and fine-grained token details.

gitlab-runner-tui

On first run, the setup asks for:

• the GitLab URL;
• the personal access token;
• a runner discovery mode; and
• optional group or project targets.

The token prompt is masked. Outside Docker, the application stores the token in macOS Keychain, Windows Credential Manager, or Secret Service on Linux and other Unix desktops. The configuration file stores only non-secret settings.

The all mode falls back to visible if GitLab returns 403 Forbidden. The targets mode is usually the clearest choice for GitLab.com or a token with limited scope. Enter targets with an explicit prefix:

group:my-org/platform,project:my-org/application

A target can use a numeric GitLab ID or a group or project path.

The dashboard has seven views:

Useful keys:

Add a command to skip the dashboard and return machine-readable output:

Examples:

# Fast inventory
gitlab-runner-tui fetch --summary

# Full data for production runners
gitlab-runner-tui fetch --tags production

# Offline runners on a specific runner version
gitlab-runner-tui switch --tags production --version 17.11

# Runners that have not contacted GitLab since 11:00 local time
gitlab-runner-tui flames --stale-cutoff 11:00

# Check whether matching runners have overlapping managers
gitlab-runner-tui rotating --tags production

Normal query commands write one JSON document. The document contains runners and metrics:

gitlab-runner-tui fetch --summary | jq '.runners[] | {id, status}'
gitlab-runner-tui fetch | jq '.metrics.request_counts'

fetch --summary omits runner details and managers. It cannot be combined with --version, because version filtering needs enriched runner data.

The rotation waiter polls until every eligible matching runner has rotated:

gitlab-runner-tui rotating --wait --tags production

It writes newline-delimited JSON events while it runs. It exits with status 0 when rotation completes and status 2 when the configured timeout expires. See the CLI and automation guide for the event fields and waiter configuration.

The default configuration file is:

The settings screen edits the same file. A minimal target-based configuration looks like this:

gitlab_host = "https://gitlab.example.com"
discovery_mode = "configured_targets"
poll_interval_secs = 30
poll_timeout_secs = 1800
max_enrichment_requests = 10

[[runner_targets]]
kind = "group"
id = "my-org/platform"
label = "Platform"

[[runner_targets]]
kind = "project"
id = "my-org/application"

max_enrichment_requests controls concurrent runner-detail and manager requests. The default is 10; accepted values are 2 through 64.

The application does not discover config.toml or .env files from the current directory. Select another file explicitly:

gitlab-runner-tui --config /trusted/path/config.toml
gitlab-runner-tui --dotenv /trusted/path/runtime.env

Only select files you trust. A selected file can change the GitLab host that receives your token.

Use these commands to inspect or remove saved credentials without showing the token:

gitlab-runner-tui auth status
gitlab-runner-tui auth logout

For a temporary override, set environment variables for the process:

GITLAB_HOST=https://gitlab.example.com \
GITLAB_TOKEN=glpat-example \
gitlab-runner-tui fetch --summary

GITLAB_TOKEN takes priority over the saved credential. It is not written to the operating system credential store or configuration file. The application does not accept tokens as command-line arguments because process listings and shell history can expose them.

Run the dashboard with a named volume:

docker run --rm -it \
  --env XDG_CONFIG_HOME=/config \
  --mount type=volume,source=gitlab-runner-tui-config,target=/config \
  ghcr.io/damacus/gitlab-runner-tui:latest

The first run starts setup and writes /config/gitlab-runner-tui/config.toml. The official container has no system credential store, so the token is saved in that configuration volume. Protect access to the Docker daemon and volume.

For automation, pass a protected environment file instead of putting the token in the command:

GITLAB_HOST=https://gitlab.example.com
GITLAB_TOKEN=glpat-example

chmod 600 /trusted/path/gitlab-runner-tui.env
docker run --rm \
  --env-file /trusted/path/gitlab-runner-tui.env \
  ghcr.io/damacus/gitlab-runner-tui:latest fetch --summary

Users with access to the Docker daemon can inspect container environment variables while the container exists. Use a trusted read-only bind mount with --dotenv if the token must stay out of the Docker-managed environment.

Each release also publishes ghcr.io/damacus/gitlab-runner-tui-ci. That image includes sh, bash, grep, and jq, and has no application entrypoint so GitLab Runner can execute job scripts normally.

Run gitlab-runner-tui auth status, then check:

• the token has not expired;
• the token has the required runner permissions;
• the token owner can access the selected groups, projects, or instance runners; and
• GITLAB_HOST is the expected GitLab instance.

If GITLAB_TOKEN is set, it overrides the saved credential.

The all discovery mode needs administrator or auditor access. Use visible or targets for a more limited account, or grant the required GitLab role and token permissions.

• Clear active tag, status, and version filters.
• Check the selected discovery mode in settings.
• In targets mode, confirm each group or project ID or path.
• Confirm that the token owner can see the runners in GitLab.

Unlock the desktop credential store before starting the application. For a temporary session, set GITLAB_TOKEN. The native application does not fall back to saving a plaintext token.

Custom certificate authorities and insecure TLS are not currently supported.

Issues and pull requests are welcome. This repository uses mise for its pinned development tools. Run mise install and mise run check before submitting a change.

• Open an issue
• Start a discussion

GitLab Runner TUI is available under the MIT Licence.