A terminal UI (TUI) application for managing GitLab projects — Merge Requests, Pipelines, and Issues — from your terminal.
Built with BubbleTea and the official GitLab API client. A GitHub counterpart lives in github-tui.
- 🔀 Merge Requests — list, filter by state (open/merged/closed), view details, approve, merge, close, edit existing MRs, and create new MRs via an interactive wizard
- 🌿 Branches — list branches, delete branch (with confirmation), create MR directly from a branch, view commits history, and compare branches (showing commit differences and changed files diff)
- 🏷️ Tags — list tags, create new tag (title, create from branch/ref selector, description), edit tag release notes (
e), delete tag (with confirmation), view commit history of a tag, and toggle commit diff pane withTab - 🚀 Pipelines — list, view details (with dual-pane layout showing jobs and statuses), automatic background refresh (every 5s) for active pipelines, retry/cancel pipelines, restart individual jobs, scroll/search job trace logs, and open traces directly in your external editor
- 📦 Container Registry — list image repositories, view repository tags (with creation date, size, and path), sort tags by creation date (
sto toggle desc/asc), delete image repositories or specific tags (with confirmation), and view extended tag details - 🐛 Issues — list, filter by state (open/closed/all), view details with discussion threads & comments, create new issues (
c), edit existing issues (e), create branch for issue (b), close (x), reopen (O), post new comments, vote up/down, select/edit/delete comments - 📁 Projects — browse and switch projects on the current server
- 🔌 Multiple servers — configure several GitLab instances, switch between them
- 🧠 Auto-detection — detects server and project from the current directory's
git remote - 🔗 Open links — press
oon MR, pipeline, or issue detail to see all links (WebURL, links in descriptions and comments) and open them in your browser - 📋 Yank to clipboard — press
yon MR, pipeline, or issue detail for a quick-copy popup: MR/issue/pipeline ID, title, description, source branch (MRs), or any URL found in the item; multiple URLs open a pick list - 🎫 YouTrack integration — automatically parses issue tracker keys (like
PROJ-XXXX) in descriptions and comments, resolving them to YouTrack URLs inside the link selection menu - 🎨 Themes — support for
"catppuccin"(default dark theme with purple/indigo accents) and"teams"(green borders, dark grey panels, purple highlights)
To build and install the binary:
# Install to /usr/local/bin (may require sudo)
make install
# Or install to a custom path (e.g. ~/.local/bin) without sudo
make install PREFIX=$HOME/.localOr just build without installing:
make build
./gitlab-tuiYou can start gitlab-tui in the current directory's auto-detected project (or select a project inside the TUI):
gitlab-tuiYou can pass a GitLab URL (Merge Request, Pipeline, or Job) as an argument to open that resource directly on startup:
# Open a merge request directly
gitlab-tui https://gitlab.com/group/project/-/merge_requests/123
# Open a pipeline directly
gitlab-tui https://gitlab.com/group/project/-/pipelines/33780
# Open a job trace directly
gitlab-tui https://gitlab.com/group/project/-/jobs/155933On first run, a sample config is created at:
~/.config/gitlab-tui/config.json
Edit it to add your servers:
{
"servers": [
{
"name": "gitlab.com",
"url": "https://gitlab.com",
"token": "glpat-xxxxxxxxxxxxxxxxxxxx",
"default": true
},
{
"name": "company-gitlab",
"url": "https://gitlab.company.com",
"token": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
],
"youtrack_servers": [
{
"name": "company-youtrack",
"url": "https://youtrack.company.com",
"projects": ["PROJ1", "PROJ2"]
}
],
"browser_command": "xdg-open",
"youtrack_command": "yt-tui",
"theme": "catppuccin"
}| Option | Default | Description |
|---|---|---|
servers |
— | List of GitLab server configurations |
youtrack_servers |
— | List of YouTrack server configurations to resolve ticket keys to URLs (each server has name, url, and a list of projects) |
browser_command |
"xdg-open" |
Command to open URLs (e.g. "firefox", "google-chrome", "brave-browser"). Leave as "xdg-open" to use your system default browser. |
youtrack_command |
— | Command to open YouTrack URLs specifically (e.g. yt-tui). When set, any URL belonging to a configured YouTrack server is opened via this command instead of browser_command. |
theme |
"catppuccin" |
TUI theme. Supported values: "catppuccin" (default) or "teams" (green borders, dark grey panels, purple highlights). |
A server token may be a literal personal access token, or a reference to a variable in ~/.config/gitlab-tui/.env (same folder as config.json). Use $NAME or ${NAME}:
{
"name": "gitlab.com",
"url": "https://gitlab.com",
"token": "$GITLAB_COM_TOKEN"
}# ~/.config/gitlab-tui/.env
GITLAB_COM_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
The file is read when the config loads. A name set there overrides the same variable in the process environment. If it is missing from the file, the process environment is used. The resolved value stays in memory and is not written back into config.json.
You need a Personal Access Token with at least api scope. Create one at:
https://gitlab.com/-/user_settings/personal_access_tokens
When you run gitlab-tui from inside a git repository, it reads git remote get-url origin and matches it against your configured servers.
Both SSH and HTTPS remotes are supported:
git@gitlab.com:mygroup/myproject.githttps://gitlab.com/mygroup/myproject.git
| Key | Action |
|---|---|
Tab / → |
Next tab |
Shift+Tab / ← |
Previous tab |
1–7 |
Jump to tab (MRs, Branches, Tags, Pipelines, Registry, Issues, Projects) |
j / ↓ |
Move down |
k / ↑ |
Move up |
Enter |
Open detail / select project / show commits / open image tags |
s |
Cycle MR/Issue state filter, or toggle Container Registry tag sort order |
c |
Create new MR, Tag, or Issue (MRs, Branches, Tags, Issues) |
C |
Compare branch with another (Branches tab only) |
b |
Create branch for issue (Issues tab only) |
d |
Delete branch, tag, registry image, or registry tag (with confirmation) |
e |
Edit selected MR, Tag, or Issue (MRs, Tags, and Issues tabs) |
x |
Close selected MR or Issue |
O |
Reopen selected MR or Issue |
r |
Refresh current tab |
n / p |
Next / previous page |
P |
Switch project |
S |
Switch server |
q / Ctrl+C |
Quit |
| Key | Action |
|---|---|
j / k |
Scroll detail |
n / N |
Select next / previous comment (J / K also supported) |
Tab |
Toggle changes panel |
C |
Post new comment |
r |
Reply to selected comment thread |
e |
Edit selected comment (or edit MR if no comment selected) |
d |
Delete selected comment |
a |
Approve MR |
m |
Merge MR |
x |
Close MR |
O |
Reopen MR (closed MRs) |
+ / - |
Vote up / down |
o |
Open link selector |
y |
Yank (copy) MR ID, title, description, branch, or URLs |
p |
Open pipeline selector |
Esc |
Clear comment selection (if active) or back to list |
| Key | Action |
|---|---|
j / k |
Scroll commits list / changed files list / diff lines |
Tab |
Toggle focus between commits panel and files panel (compare view) |
Enter |
View branch commits (main list) / expand file diff (compare files) |
Esc |
Go back (exit diff, exit comparison list, or return to branch list) |
| Key | Action |
|---|---|
j / k |
Scroll commits list / navigate diff lines |
Tab |
Toggle diff pane for selected commit |
n / p |
Next / previous file in diff pane |
J / K |
Next / previous hunk in diff pane |
e |
Edit release notes for this tag |
Esc |
Close diff pane (if open) or return to tag list |
| Key | Action |
|---|---|
Enter |
Open image to view tags / Open tag to view detailed info |
s |
Toggle tag creation date sort order (descending / ascending) |
d |
Delete highlighted image repository (view 0) or tag (view 1) with prompt |
Esc |
Go back one level (Tag Detail → Tag List → Image List) |
Press e on the tag list or in the tag detail view to open the Edit Tag popup.
- Tag Name is shown read-only.
- Release Description / Notes is a multiline textarea — edit freely and press
Ctrl+Sto save, orEscto cancel. - Changes are saved as a GitLab Release associated with the tag (creating one if none exists yet).
Press c on the MR list tab to open the Create MR wizard. It guides you through three steps:
Press e on either the MR list tab (for the highlighted MR) or the MR detail page to open the Edit MR popup. It loads the MR's current fields:
- Title (excluding any
Draft:orWIP:prefix) - Mark as Draft checkbox
- Description
- Delete source branch checkbox
- Squash commits checkbox
Using the same form navigation keys as the Create MR wizard (Tab, Shift+Tab, Space, Ctrl+S, Esc), you can modify these details and save your changes.
Step 1 — Source branch Pick the branch you want to merge from. All project branches are shown in a scrollable list.
Step 2 — Target branch Pick the destination branch. The source branch is excluded from the list. The repository's default branch is pre-selected.
Step 3 — Details form
| Field | Default | Notes |
|---|---|---|
| Title | Branch name (humanized) | Pre-filled from source branch name |
| Mark as Draft | ☐ Off | Prefixes title with Draft: |
| Description | Last commit body | Auto-fetched from the source branch's latest commit |
| Delete source branch | ✓ On | Removes branch after merge |
| Squash commits | ☐ Off | Squashes all commits on merge |
Form navigation:
| Key | Action |
|---|---|
Tab |
Next field |
Shift+Tab |
Previous field |
Space / Enter |
Toggle focused checkbox |
Ctrl+S |
Submit and create the MR |
Esc |
Go back one step (or cancel) |
Note: When the Description textarea is focused,
Enterinserts a newline. UseCtrl+Sto submit, orTab/Shift+Tabto leave the textarea.
Press c on the Issues list tab to open the Create Issue popup, or press e on the Issues list tab (or on the Issue detail page when no comment is selected) to edit an existing issue.
| Field | Notes |
|---|---|
| Title | Issue title |
| Type | Issue type (issue, incident, task) |
| Description | Issue description body |
Form navigation:
| Key | Action |
|---|---|
Tab |
Next field |
Shift+Tab |
Previous field |
← / → |
Cycle issue type |
Ctrl+S |
Save / create the issue |
Esc |
Cancel |
Note: When editing an issue, the type selector dynamically hides options disallowed by GitLab's API (such as converting existing issues/incidents to
task), preventing API errors.
Press b on the Issues list tab (for the highlighted issue) or on the Issue detail page to open the Create Branch for Issue popup.
| Field | Notes |
|---|---|
| Branch Name | Name of new branch. Pre-filled with <iid>-<title-slug> (e.g. 42-fix-login-bug) |
| Source Ref | Source branch, tag, or commit SHA (pre-filled with default project branch) |
Form navigation:
| Key | Action |
|---|---|
Tab |
Next field |
Shift+Tab |
Previous field |
Enter / Ctrl+S |
Submit and create branch |
Esc |
Cancel |
| Key | Action |
|---|---|
j / k |
Select job / Navigate jobs list |
Enter |
View trace/log output for the selected job |
r |
Restart/retry selected job (requires confirmation) |
R |
Retry entire pipeline |
c |
Cancel pipeline |
o |
Open link selector |
y |
Yank (copy) pipeline ID, ref, or URL |
Esc |
Back to list (or close trace view if open) |
Inside trace view:
j/k(or down/up): Scroll trace log linesPgUp/PgDn: Scroll one pageCtrl+d/Ctrl+u: Scroll half pageg/G: Scroll trace to top / bottomCtrl+G: Open trace in external editor (reads$EDITOR, falls back tovim)Esc/Enter/Tab: Close trace view
| Key | Action |
|---|---|
j / k |
Scroll detail |
n / p |
Select next / previous comment (J / K also supported) |
C / c |
Post new comment |
r |
Reply to selected comment thread |
e |
Edit selected comment (or edit Issue if no comment selected) |
b |
Create branch for issue |
d |
Delete selected comment |
x |
Close Issue |
O |
Reopen Issue (closed issues) |
+ / - |
Vote up / down |
o |
Open link selector |
y |
Yank (copy) issue ID, title, description, or URLs |
Esc |
Clear comment selection (if active) or back to list |
.
├── cmd/gitlab-tui/main.go # Entrypoint
├── internal/
│ ├── config/config.go # Config loading + git auto-detection
│ ├── gitlab/client.go # GitLab API wrapper
│ └── tui/
│ ├── model.go # BubbleTea model (update + view)
│ └── styles.go # Lipgloss styles + colors
└── Makefile
- github-tui — sibling TUI for GitHub: pull requests, issues, Actions, branches, and tags. Same Bubble Tea layout, keys, config shape, and YouTrack links.
See LICENSE.
Hope you liked it. Wanna buy Me a coffee?