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

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, the SystemGhRunner executes gh commands and converts errors through map_gh_error. GitLab and Bitbucket follow analogous patterns in src/forge/gitlab/glab.rs and 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.

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 ."

Command failures – All other errors produce: "GitHub command failed: " 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. This prevents API endpoint mismatches when parsing remote URLs through parse_github_remote_url.

GitHub Resolution Steps

Verify and restore GitHub authentication:

# 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, 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 ."

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

GitLab Resolution Steps

# 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.

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 ."

Bitbucket Resolution Steps

# 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

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

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

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, src/forge/gitlab/glab.rs, and 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.
• 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}