RFC: GitHub-aware repository tabs and a clearer key guide

[777lotto]

Summary

GitPanel already gives a strong keyboard-first view of local repository state, but two surfaces now need to grow together:

1. the ? key guide is a dense, flat list that is difficult to scan; and
2. repository work frequently continues on GitHub, requiring a context switch for Actions, Issues, and Pull Requests.

This RFC proposes a clearer key guide and optional, read-only GitHub repository tabs while preserving the plugin's lightweight local Git core.

Tracking implementation: issue #5

Proposed experience

The panel gains a persistent view bar:

[1 Changes]  [2 History]  [3 Actions]  [4 Issues]  [5 Pull Requests]

• <Tab> and <S-Tab> move forward/backward; 1 through 5 jump directly.
• Changes and History retain today's local Git behavior.
• Actions, Issues, and Pull Requests fetch the repository associated with the current checkout.
• Remote views render cached content immediately, refresh asynchronously when stale, and expose loading/error/last-updated state.
• <CR> opens an in-editor detail; gx opens the canonical GitHub page.
• The first release is deliberately read-only, which keeps permissions and failure modes understandable.

The ? popup becomes a responsive Key Guide built from structured sections rather than hand-aligned prose. Navigation, files, conflicts, commits, branches/worktrees, remotes, GitHub, and general controls receive distinct headings; keys and warnings receive semantic highlights; q/Esc close and ordinary motions scroll when the editor is short.

Transport: gh is recommended, not required

The proposed provider order is:

1. GitHub CLI (gh api) when installed. This is the smoothest path because gh owns credential storage and supports GH_TOKEN, GITHUB_TOKEN, GH_HOST, and enterprise equivalents.
2. curl REST fallback for users who do not want gh. Public repositories can be read anonymously; private repositories use a bearer token supplied at request time.
3. Custom provider hook for specialized environments.

Both built-in transports use the current supported GitHub REST API contract, normalize responses into plain Lua models, and run through vim.system() callbacks so network latency never blocks editing.

GitHub App OAuth tokens and private keys

GitHub App user access tokens and installation access tokens are bearer tokens and can call the three read endpoints when the App has Actions, Issues, and Pull requests read permissions.

A GitHub App private key is not an API token. It signs an RS256 JWT, which is then exchanged for an installation access token; installation tokens expire after one hour. GitPanel should not read or store that long-lived private key. Instead, setup accepts a token_provider callback that can invoke the user's existing helper/vault and return a fresh short-lived token whenever a request batch begins.

Illustrative configuration:

require("git_panel").setup({
  github = {
    transport = "auto", -- gh, then curl
    token_provider = function(host, repo)
      return my_secure_helper.github_installation_token(host, repo)
    end,
  },
})

Users with a normal authenticated gh session need no token configuration at all. Tokens must never be persisted, displayed, logged, or placed in process arguments.

Primary references:

• GitHub CLI token and host environment
• About GitHub App authentication
• Installation access tokens
• Workflow runs, Issues, and Pull requests endpoint permissions

Delivery slices

1. Structured, highlighted, responsive key guide plus shared UI helpers.
2. setup() contract, GitHub remote detection, async provider interface, cache, and deterministic fixtures.
3. Actions view and detail state.
4. Issues and Pull Requests views and detail state.
5. Documentation, compatibility pass, and promotion through the repository's bluff → bet release flow.

Each slice will update the tracking issue; implementation will be reviewed in a draft PR targeting bluff.

Feedback requested

• Are the five view names and <Tab> / <S-Tab> / numeric navigation intuitive?
• Is gh-first with a curl fallback the right balance for a dependency-free-by-default plugin?
• Which fields are essential in the compact Actions, Issues, and Pull Requests rows?
• Should the in-editor detail be a split, a float, or configurable after the first read-only release?
• Which GitHub Enterprise remote formats or credential helpers should be represented in fixtures?

The security boundary (no raw App private key in Neovim) and nonblocking network behavior are intended to be hard requirements.

[777lotto]

Implementation checkpoint

Draft PR #7 now carries the first complete implementation from signed commit 5ee8df1.

• the ? guide is structured, responsive, highlighted, and scrollable
• the panel has Changes, History, Actions, Issues, and Pull Requests views
• GitHub synchronization is asynchronous, read-only, cached per repository/view, and supports authenticated gh or hardened curl
• GitHub App user/installation access tokens work through sync or async providers; raw private keys remain in an external token-minting helper or vault
• unit/provider/redaction/renderer coverage, expanded Git fixture smoke coverage, user help, security guidance, changelog, CI, and contribution templates are included

Validation is green on exact pinned Neovim 0.10.4 and 0.12.4. Live Actions, Issues, and Pull Requests reads also pass through authenticated gh and anonymous curl against this repository.

The PR remains a draft for the first visual review and an updated screenshot/recording: #7

[777lotto]

Validation complete

Follow-up commit 4a0d56c adds deterministic coverage proving that a stale response from an earlier repository generation cannot replace current data. GitHub reports both commits' signatures as valid.

The updated PR is green across Linux Neovim 0.10.4, 0.11.7, and 0.12.4, macOS Neovim 0.12.4, and the quality job. The implementation checklist above is now complete.

PR #7 remains a draft only for the visual review and updated screenshot/recording.

[777lotto]

Delivered through PR #7 and promoted from bluff to the default bet branch by PR #8 (merge 6d074e6). All required CI checks passed, the promotion has no review threads, and tracking issue #5 is closed as completed. No project card was attached to this work. Closing this RFC as implemented.