Documentation
¶
Overview ¶
Package github creates the authenticated GitHub API client marge uses.
Index ¶
- Variables
- func APITransport() *http.Transport
- func AppWriteAccess(client *github.Client) func(ctx context.Context, owner, repo string) (bool, error)
- func AuthenticatedLogin(ctx context.Context, client *github.Client) (string, error)
- func CallerToken(ctx context.Context) string
- func ContextWithBearer(ctx context.Context, r *http.Request) context.Context
- func ContextWithCallerToken(ctx context.Context, token string) context.Context
- func GraphQLURL(client *github.Client) (string, error)
- func ListOpenPRs(ctx context.Context, client *github.Client, refs []RepoRef) ([]OpenPR, []RepoFailure)
- func LoadToken(ctx context.Context) string
- func NewAppClient(app *App, baseURL string, httpClient *http.Client) (*github.Client, error)
- func NewCallerClient(ctx context.Context) (*github.Client, error)
- func NewClient(ctx context.Context) (*github.Client, error)
- func RequireBearer(next http.Handler) http.Handler
- type App
- type InstallationToken
- type OpenPR
- type RepoFailure
- type RepoRef
Constants ¶
This section is empty.
Variables ¶
var ErrNoCallerToken = errors.New("not signed in: this server acts as the person calling it and the request carried no GitHub token. Sign in to the marge MCP server (core_auth_login in muster) and retry")
ErrNoCallerToken is returned when a request carried no bearer token. It is never an invitation to authenticate as something else: a served call belongs to the person who made it, and no request is answered with the App's identity or with a token the process happens to hold.
Functions ¶
func APITransport ¶ added in v0.30.1
APITransport returns the connection pool every GitHub client shares. One pool across the process is what lets a second tool call reuse the connections the first one opened.
func AppWriteAccess ¶ added in v0.19.2
func AppWriteAccess(client *github.Client) func(ctx context.Context, owner, repo string) (bool, error)
AppWriteAccess returns a check of whether the App installation behind the client may write to a repository, or nil when the client authenticates with a person's token. A nil result is the signal to keep reading permissions.push from the repository, which is the only answer a user token has.
The check reads the permissions GitHub reports when it mints the token the call would carry, so it describes that token and nothing else. The token is already minted for every repository the sweep touches, so the check costs no extra request.
func AuthenticatedLogin ¶ added in v0.19.0
AuthenticatedLogin returns the login the client acts as. An installation token has no user behind it, so GET /user answers 403 and the App's own slug names the bot instead.
The answer comes from the client, not from the environment: a process may hold the App credential and still serve a call with a person's token, and that call is the person's.
func CallerToken ¶ added in v0.21.0
CallerToken returns the caller's token, or "" when the request carried none.
func ContextWithBearer ¶ added in v0.21.0
ContextWithBearer carries the request's bearer token on ctx. It is the mcp-go HTTP context hook of the streamable transport, so every tool call of a session sees the token that arrived with it.
func ContextWithCallerToken ¶ added in v0.21.0
ContextWithCallerToken carries token on ctx. An empty token is left off, so a later read cannot tell it from no header at all.
func GraphQLURL ¶ added in v0.30.1
GraphQLURL returns the GraphQL endpoint of the API a client talks to. go-github speaks REST only, so the endpoint is derived from the REST root: github.com serves it at /graphql, and GitHub Enterprise Server next to the /api/v3 root it was given.
func ListOpenPRs ¶ added in v0.30.1
func ListOpenPRs(ctx context.Context, client *github.Client, refs []RepoRef) ([]OpenPR, []RepoFailure)
ListOpenPRs returns the open pull requests of every repository named, and the repositories it could not read.
One GraphQL request covers reposPerQuery repositories, so a scope of a few hundred repositories costs a handful of requests instead of one per repository. The order of the answer follows the order of refs, so the same scope lists the same way twice.
func LoadToken ¶
LoadToken returns the GitHub token from GITHUB_TOKEN, GH_TOKEN or, failing both, the GitHub CLI's own login (`gh auth token`). It returns "" when none of them yields a token.
func NewAppClient ¶ added in v0.19.0
NewAppClient returns a client that authenticates as the App against baseURL. A nil httpClient uses the default transport. Only the tests pass either argument; NewClient supplies GitHub's own.
func NewCallerClient ¶ added in v0.21.0
NewCallerClient returns a GitHub client authenticated with the token the caller presented, so every read and write lands as that person. It reads no environment variable and no App credential: the process may hold both, and either would make a write the bot's rather than the caller's.
func NewClient ¶
NewClient returns a GitHub API client. It authenticates as the sweep App when the environment carries the App credential, and with the token LoadToken finds otherwise.
func RequireBearer ¶ added in v0.25.3
RequireBearer refuses a request that carries no bearer token with 401 and a Bearer challenge, before next sees it. Without the challenge muster's connect-time probe, which carries no token, succeeds, and muster then serves the endpoint as a shared unauthenticated server: no sign-in is ever offered and every tool call fails for want of a caller. The 401 is what makes muster hold the server at "Auth Required" until a person completes core_auth_login.
Types ¶
type App ¶ added in v0.19.0
App is the sweep GitHub App's credential. It mints installation tokens on demand and holds no token beyond the life of the process.
func LoadApp ¶ added in v0.19.0
LoadApp returns the App credential the environment carries, or nil when it carries none, which is not an error: the token path serves a person running the CLI. A partial credential is an error, because it is a misconfigured unattended run and not a person's shell.
func (*App) JWT ¶ added in v0.19.0
JWT returns the App JWT that authenticates marge as the App itself, which is what the token mint and GET /app accept.
func (*App) MintToken ¶ added in v0.19.0
func (a *App) MintToken(ctx context.Context, httpClient *http.Client, baseURL string, repos []string) (InstallationToken, error)
MintToken returns an installation token for the named repositories. GitHub scopes the token to those repositories alone: every other repository of the installation answers 404 under it.
type InstallationToken ¶ added in v0.19.2
InstallationToken is one minted token, the moment it stops working, and the permissions GitHub reports for it. The permissions are the token's own authority, which is the only trustworthy answer to what an installation may do: GET /repos reports permissions for the authenticated user, and an installation token has no user behind it.
type OpenPR ¶ added in v0.30.1
type OpenPR struct {
Owner string
Repo string
Number int
Title string
URL string
Author string
BaseRef string
CreatedAt time.Time
Labels []string
}
OpenPR is one open pull request as a repository listing reports it.
type RepoFailure ¶ added in v0.30.1
RepoFailure names a repository whose pull requests could not be listed, and why. A repository that fails to list is reported, never silently dropped from a sweep.
type RepoRef ¶ added in v0.30.1
RepoRef is one repository to list, as owner and name.
func ParseRepoRefs ¶ added in v0.30.1
ParseRepoRefs reads "owner/name" entries. An entry that does not name both is dropped, exactly as the repository list of a team file is read today.
Source Files