# How to Troubleshoot Forge Authentication for GitHub, GitLab, and Bitbucket in tuicr

> Troubleshoot forge authentication for GitHub, GitLab, and Bitbucket in tuicr. Fix common errors by verifying CLI tools, token scopes, and host configurations for seamless integration.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-07

---

**To troubleshoot forge authentication errors in tuicr, ensure the respective CLI tools (`gh`, `glab`, `bkt`) are installed and authenticated, verify token scopes include `repo` (GitHub), `api` (GitLab), or `pullrequest:write` (Bitbucket), and check enterprise host configurations.**

tuicr interacts with remote forges through the command-line tools `gh`, `glab`, and `bkt`. When authentication problems occur, the Rust application converts low-level CLI errors into user-friendly `TuicrError::Forge` messages. Understanding how these errors are detected and mapped in the source code enables rapid diagnosis of authentication failures.

## How tuicr Detects Authentication Failures

The application delegates forge operations to external CLI runners. In [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs), the `SystemGhRunner` executes `gh` commands and converts errors through `map_gh_error`. GitLab and Bitbucket follow analogous patterns in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs) and [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs) respectively.

When a command fails, tuicr analyzes stderr output for specific patterns:

- "not logged in" or "auth login" prompts trigger authentication failure messages
- Missing binary errors indicate the CLI tool is not installed
- HTTP status codes (403, 401) reveal permission or scope issues

## Troubleshooting GitHub Authentication

GitHub integration relies on the `gh` CLI tool. Authentication errors surface through the `map_gh_error` function in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs).

### Common GitHub Error Patterns

The backend detects three primary failure modes:

**Missing CLI binary** – When `gh` is not found in PATH, tuicr emits: "GitHub integration requires `gh`. Install GitHub CLI and run `gh auth login`."

**Authentication status** – If stderr contains "not logged in" or references `gh auth login`, tuicr displays: "GitHub authentication failed. Run `gh auth login` for **<host>**."

**Command failures** – All other errors produce: "GitHub command failed: **<detail>**" including status codes or raw stderr.

### Enterprise Host Normalization

For GitHub Enterprise instances using SSH-over-HTTPS transport, tuicr normalizes `ssh.github.com` back to `github.com` via `normalize_ssh_transport_host` at line 445 of [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs). This prevents API endpoint mismatches when parsing remote URLs through `parse_github_remote_url`.

### GitHub Resolution Steps

Verify and restore GitHub authentication:

```bash

# Verify CLI presence

which gh && gh --version

# Show current authentication status

gh auth status

# (Re)authenticate

gh auth login

```

Ensure your token includes the **`repo`** and **`pull_request:write`** scopes for full functionality.

## Troubleshooting GitLab Authentication

The GitLab backend mirrors GitHub's implementation in [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs), running `glab` commands and mapping errors analogously to `map_gh_error`.

### GitLab Error Patterns

**Missing binary** – "GitLab integration requires `glab`. Install GitLab CLI and run `glab auth login`."

**Authentication required** – "GitLab authentication failed. Run `glab auth login` for **<host>**."

**Permission failures** – 403 errors indicate the token lacks the required **`api`** scope.

### GitLab Resolution Steps

```bash

# Verify CLI installation

which glab && glab --version

# Check authentication status

glab auth status

# Authenticate or re-authenticate

glab auth login

```

The personal access token must have the **`api`** scope to enable tuicr's pull request operations.

## Troubleshooting Bitbucket Authentication

Bitbucket integration uses the `bkt` CLI tool, with error handling implemented in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs).

### Bitbucket Error Patterns

**Missing binary** – "Bitbucket integration requires `bkt`. Install Bitbucket CLI and run `bkt auth login`."

**Authentication required** – "Bitbucket authentication failed. Run `bkt auth login` for **<host>**."

### Bitbucket Resolution Steps

```bash

# Verify CLI availability

which bkt && bkt --version

# Display current login status

bkt auth status

# Login or refresh authentication

bkt auth login

```

Bitbucket Cloud requires an OAuth app or personal access token with the **`pullrequest:write`** permission.

## Resolving Authentication Errors

Follow this systematic approach when tuicr displays forge authentication errors:

1. **Confirm CLI availability** – Run `which gh`, `which glab`, and `which bkt` to ensure tools are installed. Install missing binaries via package managers (`brew install gh`, `cargo install glab`, etc.).

2. **Validate login status** – Execute `gh auth status`, `glab auth status`, or `bkt auth status` to verify active sessions and associated accounts.

3. **Check token scopes** – 
   - GitHub: requires `repo` and `pull_request` scopes
   - GitLab: requires `api` scope
   - Bitbucket: requires `pullrequest:write` permission

4. **Inspect enterprise configurations** – For GitHub Enterprise, ensure the host is reachable and SSH-over-HTTPS transport hosts are properly normalized via `normalize_ssh_transport_host`.

5. **Reload the repository** – After fixing authentication, press `:e` in the TUI to reload pull request details and diffs.

## Programmatic Error Handling

The following Rust patterns demonstrate how tuicr handles authentication internally according to the `agavra/tuicr` source code.

### Checking GitHub Authentication

```rust
use crate::forge::github::gh::{SystemGhRunner, map_gh_error, GhCommandError};

fn verify_github_auth(host: &str) -> Result<(), TuicrError> {
    let runner = SystemGhRunner;
    match runner.run(&["auth", "status".to_string()]) {
        Ok(_) => Ok(()),
        Err(err) => Err(map_gh_error(err, host)),
    }
}

```

### Handling GitLab Permission Failures

```rust
fn map_glab_error(err: GlabCommandError, host: &str) -> TuicrError {
    match err {
        GlabCommandError::MissingGlab => TuicrError::Forge(
            "GitLab integration requires `glab`. Install it and run `glab auth login`."
                .into(),
        ),
        GlabCommandError::Failed { stderr, .. } if stderr.contains("403") => {
            TuicrError::Forge(
                "GitLab token lacks required `api` scope. Update the token and retry."
                    .into(),
            )
        }
        _ => TuicrError::Forge(format!("GitLab command failed: {}", err)),
    }
}

```

### Bitbucket Login Prompt Handling

```rust
let backend = BitbucketBktBackend::new(None);
match backend.list_pull_requests(query) {
    Ok(pages) => { /* process PRs */ }
    Err(TuicrError::Forge(msg)) => eprintln!("Authentication error: {}", msg),
    Err(e) => return Err(e),
}

```

## Summary

- tuicr delegates forge operations to external CLI tools (`gh`, `glab`, `bkt`) and maps their errors to `TuicrError::Forge` variants in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs), [`src/forge/gitlab/glab.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/gitlab/glab.rs), and [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs).
- Authentication failures are detected by parsing stderr for "not logged in" patterns, missing binary errors, and HTTP 403/401 status codes.
- GitHub Enterprise users must account for SSH-over-HTTPS transport normalization via `normalize_ssh_transport_host` in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs).
- Required token scopes are `repo` and `pull_request` for GitHub, `api` for GitLab, and `pullrequest:write` for Bitbucket.
- After resolving authentication issues, reload the tuicr interface with `:e` to refresh pull request data.

## Frequently Asked Questions

### What does the "not logged in" error mean in tuicr?

This error indicates the respective CLI tool (`gh`, `glab`, or `bkt`) has no active authentication session. Run the appropriate `auth login` command for your forge (e.g., `gh auth login`) and ensure the token has the required scopes for repository and pull request access.

### How do I fix "MissingGh" or similar binary not found errors?

Install the missing CLI tool and authenticate. For GitHub, install `gh` via `brew install gh` or `apt install gh`. For GitLab, install `glab`. For Bitbucket, install `bkt`. After installation, run the tool's `auth login` command to establish credentials before restarting tuicr.

### Why does tuicr fail with permission errors despite being logged in?

Your access token likely lacks required scopes. GitHub tokens need `repo` and `pull_request:write` scopes. GitLab tokens require the `api` scope. Bitbucket tokens need `pullrequest:write` permission. Regenerate your token with these scopes and run `auth login` again to update the stored credentials.

### How does tuicr handle GitHub Enterprise authentication?

tuicr detects enterprise hosts through `parse_github_remote_url` in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs). For SSH-over-HTTPS configurations, the `normalize_ssh_transport_host` function converts `ssh.github.com` back to `github.com` to ensure API endpoint compatibility. Ensure your enterprise host is reachable and your token has appropriate enterprise permissions.