Skip to content

Home

Jump to bottom
Emiliano Arango (waabox) edited this page Apr 3, 2026 · 7 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. If a job has no steps (common with GitLab CI), pressing Enter opens the logs directly.

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 (auto-opens logs if no 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.

Running Multiple Instances

gitdeck is safe to run in multiple terminals simultaneously (e.g. one per repository). Token refresh and config writes are coordinated across instances using file locking, so you won't lose your GitLab session when one instance refreshes its OAuth token.

  • Config writes are atomic (crash-safe)
  • GitLab token refresh is coordinated: only one instance refreshes, others adopt the new token from disk
  • Startup authentication is serialized to prevent multiple Device Flow prompts

Offline Handling

gitdeck handles internet disconnections gracefully instead of crashing:

  • When the connection drops, a banner appears: ⚠ No internet connection — retrying automatically...
  • The auto-refresh tick stays alive and keeps retrying in the background
  • If pipelines were already loaded, the list remains visible with the banner on top
  • When connectivity returns, a transient ✓ Back online message confirms recovery and disappears after 3 seconds
  • Manual refresh with ctrl+r also works while offline without disrupting the UI

This applies to all network operations: pipeline loads, job details, log fetches, actions (rerun/cancel), and re-authentication flows.

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