Documentation
¶
Index ¶
Constants ¶
const MaxMintDuration = 120 * time.Second
MaxMintDuration is a practical upper bound on how long a single MintToken call can take, informed by its retry schedule: fetchOIDCJWT retries up to 3 times (1s+2s backoff between attempts) and callMint retries up to 5 times (1s+2s+4s+8s backoff), for 18s of backoff spread across up to 8 HTTP round trips — each individually bounded by httpClient's 30s timeout (see doWithRetry, fetchOIDCJWT, callMint).
The literal worst case — every one of the 8 attempts hanging for the full 30s client timeout — is 258s, unrealistically long for a caller to wait out during teardown. In practice a mint-service outage produces fast failing responses dominated by the backoff schedule, not attempts that each hang the full client timeout, so MaxMintDuration is a documented practical ceiling rather than that literal worst case: comfortably above the ~18s backoff-only estimate — leaving headroom for real per-request latency across up to 8 round trips, including a slow attempt or two — while remaining well inside a CI job's own timeout.
Callers that bound MintToken with a context deadline (e.g. the post-script remint in internal/cli, #7231) should use at least this value: a shorter bound routinely cuts off retries the client itself would have completed.
Variables ¶
var ErrAuthenticationFailed = errors.New("authentication failed")
ErrAuthenticationFailed indicates that every available authentication mechanism was attempted and rejected (401) by the mint's /v1/status endpoint. Callers can use errors.Is to distinguish this from other terminal QueryStatus errors (e.g. network failures, non-2xx/non-401 responses, malformed URLs) that are not auth-related.
Functions ¶
func QueryStatus ¶ added in v0.44.0
func QueryStatus(ctx context.Context, req StatusRequest, resolveGitHubToken func() (string, error)) (*StatusResult, StatusAuthMethod, error)
QueryStatus calls GET /v1/status with auto-discovered authentication.
Discovery order (per #5879):
- GitHub Actions OIDC — attempted when ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN are set.
- GitHub user token — GH_TOKEN, GITHUB_TOKEN, or the output of `gh auth token`.
The first mechanism that yields a 200 response wins. A 401 from the first mechanism triggers fallback to the next. If all mechanisms fail, the error lists what was attempted.
resolveGitHubToken is a callback that resolves a GitHub user token. The CLI passes its resolveToken function; tests supply a stub.
Types ¶
type MintRequest ¶
type MintRequest struct {
MintURL string
Role string
Level string // optional: privilege level ("read" or "write"); server defaults to "write" when empty
Repos []string // required: specific repo names, or ["*"] for installation-wide token
TargetOrg string // optional: cross-org mint when set and differs from caller org
Audience string
}
MintRequest holds the parameters for minting a token via the fullsend mint service.
type MintResult ¶
MintResult holds the minted token and its expiry.
func MintToken ¶
func MintToken(ctx context.Context, req MintRequest) (*MintResult, error)
MintToken obtains a fresh GitHub App installation token by exchanging a GitHub Actions OIDC JWT with the fullsend token mint service.
It reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN from the environment. These are set automatically by GitHub Actions when the job declares id-token: write permission.
type StatusAuthMethod ¶ added in v0.44.0
type StatusAuthMethod string
StatusAuthMethod describes which mechanism authenticated a successful /v1/status call.
const ( // StatusAuthOIDC indicates authentication via GitHub Actions OIDC. StatusAuthOIDC StatusAuthMethod = "OIDC" // StatusAuthGitHub indicates authentication via a GitHub user token // (GH_TOKEN, GITHUB_TOKEN, or gh auth token). StatusAuthGitHub StatusAuthMethod = "GitHub" )
type StatusRequest ¶ added in v0.44.0
type StatusRequest struct {
MintURL string
Audience string // OIDC audience; defaults to the standard mint audience when empty.
}
StatusRequest holds the parameters for querying GET /v1/status.
type StatusResult ¶ added in v0.44.0
type StatusResult struct {
Org string `json:"org,omitempty"`
AllowedOrgs []string `json:"allowed_orgs,omitempty"`
Roles []string `json:"roles,omitempty"`
WorkflowHostRepos []string `json:"workflow_host_repos,omitempty"`
Version string `json:"version,omitempty"`
Commit string `json:"commit,omitempty"`
}
StatusResult holds the response from GET /v1/status.