Documentation
¶
Overview ¶
Package github implements the read-only Source for GitHub.com (and, by base URL, GitHub Enterprise Server). Auth is a GitHub App installation token, short-lived, least-privilege, and App-compatible: minted here from the App's private key, or read from a file somebody else mints it into (tokenfile.go). Metadata uses per-resource REST endpoints, not the Migrations API.
Index ¶
- Constants
- type Options
- type Source
- func (s *Source) CheckToken(ctx context.Context) error
- func (s *Source) CloneURL(_ context.Context, r source.Repo) (string, error)
- func (s *Source) FetchMetadata(ctx context.Context, r source.Repo) ([]byte, error)
- func (s *Source) GitAuthHeader(ctx context.Context) (string, error)
- func (s *Source) ListRepos(ctx context.Context, f source.Filter) ([]source.Repo, error)
- func (s *Source) UsesTokenFile() bool
Constants ¶
const DefaultMaxRateLimitWait = time.Hour
DefaultMaxRateLimitWait is the most one run waits for rate limits unless told otherwise: one hour, a full window of GitHub's primary limit.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
BaseURL string // empty = github.com; GHES: https://host/api/v3
AppID int64
InstallationID int64
PrivateKeyPEM []byte
// TokenPath names a file holding an installation token. With it the source holds no key
// and mints nothing; it reads the file before every API request and every git command.
TokenPath string
// MaxRateLimitWait bounds how long the source spends waiting for GitHub's rate limits, over
// its whole life, which is one run. Zero means DefaultMaxRateLimitWait.
MaxRateLimitWait time.Duration
}
Options configures the GitHub source: TokenPath, or AppID, InstallationID and PrivateKeyPEM.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is a read-only GitHub backend.
func New ¶
New builds a GitHub source authenticated as an App installation, with a token it mints from the App's key or one it reads from Options.TokenPath.
func (*Source) CheckToken ¶ added in v0.1.20
CheckToken makes one API request with the token in the token file, for a single page of one repository the installation can see. It is how doctor tests a token gitdr did not mint, and so cannot test by minting.
GET /installation/repositories accepts nothing but an installation token, so a personal access token fails here as it would fail the backup.
func (*Source) FetchMetadata ¶
FetchMetadata dumps per-resource metadata as gitdr.meta/v1 JSON using App-compatible per-resource REST endpoints (never the Migrations API). Every request waits out a rate limit and retries a 5xx; see call.
func (*Source) GitAuthHeader ¶
GitAuthHeader returns the installation token as a Basic auth header (username x-access-token), injected into git via env so it never hits argv.
It is asked for once per git command. With a token file it reads the file each time. In App mode the transport keeps the token it minted and mints a new one within a minute of its expiry, so a run longer than the token's hour keeps working.
func (*Source) ListRepos ¶
ListRepos returns repositories accessible to the installation, filtered. Each page waits out a rate limit and retries a 5xx; see call.
func (*Source) UsesTokenFile ¶ added in v0.1.20
UsesTokenFile reports whether the token comes from a token file rather than the App key.
Source Files