Skip to content

Home

Jump to bottom
Emiliano Arango (waabox) edited this page Feb 23, 2026 · 5 revisions

gitdeck

gitdeck logo

A terminal UI for monitoring CI/CD pipelines. Run it from any git repository and get an instant overview of pipeline runs and job statuses — no browser required.

Supports GitHub Actions and GitLab CI/CD (cloud and self-hosted).

Table of Contents

Installation

macOS (Homebrew)

brew tap waabox/gitdeck
brew install gitdeck

Linux — Debian/Ubuntu

# amd64
wget https://github.com/waabox/gitdeck/releases/latest/download/gitdeck_linux_amd64.deb
sudo dpkg -i gitdeck_linux_amd64.deb

# arm64
wget https://github.com/waabox/gitdeck/releases/latest/download/gitdeck_linux_arm64.deb
sudo dpkg -i gitdeck_linux_arm64.deb

Linux — Fedora/RHEL (RPM)

sudo rpm -i https://github.com/waabox/gitdeck/releases/latest/download/gitdeck_linux_amd64.rpm

From source

Requires Go 1.24 or later.

git clone https://github.com/waabox/gitdeck.git
cd gitdeck
go build -o gitdeck ./cmd/gitdeck
mv gitdeck /usr/local/bin/

Quick Start

cd /path/to/your/project
gitdeck

gitdeck reads the origin remote from .git/config and automatically selects the right CI provider (GitHub Actions or GitLab CI).

# Print version
gitdeck --version

Configuration

Config file location

gitdeck stores its configuration at:

~/.config/gitdeck/config.toml

The file is created automatically the first time gitdeck saves a token after authentication. You can also create it manually before the first run.

Full reference

# Number of recent pipelines to show in the list (default: 3)
pipeline_limit = 3

[github]
# OAuth App Client ID — only needed if you want to use your own app.
# gitdeck ships with a default client_id for github.com so this is optional.
client_id = ""
# OAuth access token. Written here automatically after first login.
# You can also paste a Personal Access Token (PAT) directly.
token = ""

[gitlab]
# OAuth App Application ID — only needed if you want to use your own app.
# gitdeck ships with a default client_id for gitlab.com so this is optional.
client_id = ""
# OAuth access token. Written here automatically after first login.
# You can also paste a Personal Access Token (PAT) directly.
token = ""
# Base URL of your GitLab instance. Leave empty for gitlab.com.
# Required for self-hosted GitLab.
url = ""

Using your own OAuth app

By default gitdeck uses its own pre-registered OAuth apps for github.com and gitlab.com — no configuration needed. However if you prefer to use your own app (for example to keep tokens scoped to your organization, or for a self-hosted instance), register an OAuth app and set client_id in the config:

[gitlab]
client_id = "your_application_id_here"
url = "https://gitlab.yourcompany.com"  # omit for gitlab.com

See Setting up OAuth Apps below for step-by-step instructions.

Using a Personal Access Token instead of OAuth

If you already have a PAT and don't want to go through the OAuth flow, paste it directly into the config:

[github]
token = "ghp_xxxxxxxxxxxxxxxxxxxx"

[gitlab]
token = "glpat-xxxxxxxxxxxxxxxxxxxx"

gitdeck will use the token as-is and skip the OAuth flow entirely.

Environment variable overrides

Environment variables always take precedence over the config file and require no file at all:

Variable Description
GITHUB_TOKEN GitHub OAuth token or PAT. Overrides github.token.
GITLAB_TOKEN GitLab OAuth token or PAT. Overrides gitlab.token.
GITLAB_URL GitLab instance base URL. Overrides gitlab.url. 
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_URL=https://gitlab.yourcompany.com
gitdeck

Authentication

OAuth Device Flow (recommended)

On first run, if no token is present, gitdeck starts the OAuth Device Flow automatically:

No GitHub token found. Starting OAuth authentication...
Visit:      https://github.com/login/device
Enter code: ABCD-1234
Waiting for authorization...
Authenticated. Token saved to /Users/you/.config/gitdeck/config.toml

The token is saved to the config file — subsequent runs are silent.

Environment variables

You can skip OAuth entirely by exporting a token directly:

export GITHUB_TOKEN=ghp_yourtoken
export GITLAB_TOKEN=glpat_yourtoken

Environment variables always take precedence over the config file.

Setting up OAuth Apps

GitHub

  1. Go to Settings → Developer settings → OAuth Apps → New OAuth App
  2. Set any name and homepage URL
  3. Set the callback URL to http://localhost (unused for device flow)
  4. Copy the Client ID into ~/.config/gitdeck/config.toml under [github]

GitLab

  1. Go to User Settings → Applications → Add new application
  2. Enable the read_api scope
  3. Tick Allow Device Authorization Grant
  4. Copy the Application ID into ~/.config/gitdeck/config.toml under [gitlab]
  5. For self-hosted instances, also set url = "https://your.gitlab.host"

Interface Overview

gitdeck uses a hierarchical drill-down navigation: Pipelines → Jobs → Steps. Each level is a full-width screen. Press Enter to drill down, Esc to go back.

Pipelines view (default)

 gitdeck | gitdeck / ⎇ main a7e7cc7 / feat: redesign TUI header
────────────────────────────────────────────────────────────
 Pipelines
> ● #22285124958  main               2m ago
  ✓ #22285124957  main              45s ago
  ✗ #22285124956  feat/auth          1h ago
────────────────────────────────────────────────────────────
 #22285124958 by waabox
────────────────────────────────────────────────────────────
 ↑/↓: navigate   enter: open   ctrl+r: refresh   r: rerun   x: cancel   q: quit

Jobs view (after pressing Enter on a pipeline)

 gitdeck | gitdeck / ⎇ main a7e7cc7 / feat: redesign TUI header
────────────────────────────────────────────────────────────
 Jobs for Pipeline #22285124958
> ✓ build                         12s
  ✗ test                          38s
  ○ deploy                         --
────────────────────────────────────────────────────────────
 ↑/↓: navigate   enter: steps   l: logs   esc: back   r: rerun   x: cancel   q: quit

Steps view (after pressing Enter on a job)

 gitdeck | gitdeck / ⎇ main a7e7cc7 / feat: redesign TUI header
────────────────────────────────────────────────────────────
 Steps for Job: test
> ✓ Checkout code                   2s
  ✓ Install dependencies           15s
  ✗ Run tests                      28s
  ○ Upload coverage                 --
────────────────────────────────────────────────────────────
 ↑/↓: navigate   l: logs   esc: back   q: quit

Header — shows the repo name, current branch with ⎇ symbol, short commit SHA, and first line of the commit message.

Footer — context-aware keyboard hints that change depending on the current view.

Status icons

Icon Meaning
● Running
✓ Success
✗ Failed
○ Pending
⊘ Cancelled

Keyboard Shortcuts

Navigation

Key Action
↑ / ↓ Navigate items / scroll logs
Enter Drill down: Pipelines → Jobs → Steps
Esc Go back: Steps → Jobs → Pipelines / close log viewer
ctrl+r Force refresh pipelines
q / Ctrl+C Quit

Actions

Key Where Action
l Jobs, Steps Open full log viewer for selected job
r Pipelines, Jobs Re-run selected pipeline (asks confirmation)
x Pipelines, Jobs Cancel selected pipeline (asks confirmation)

Log viewer

Key Action
↑ / ↓ Scroll one line
PgUp / PgDn Scroll one page
g Jump to top
G Jump to bottom
Esc Close logs

Log Viewer

Press l from the Jobs or Steps view to open the full log output in a fullscreen scrollable panel.

 gitdeck  waabox/gitdeck  [logs] build
────────────────────────────────────────────────────────────
Run actions/checkout@v4
  with:
    repository: waabox/gitdeck
...
────────────────────────────────────────────────────────────
 ↑/↓: scroll   PgUp/PgDn: page   g/G: top/bottom   esc: back

Press Esc to return to the previous view.

Environment Variables

Variable Description
GITHUB_TOKEN GitHub personal access token or OAuth token. Overrides config file.
GITLAB_TOKEN GitLab personal access token or OAuth token. Overrides config file.
GITLAB_URL GitLab instance base URL (for self-hosted). Overrides config file.

Clone this wiki locally