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 within oidcRetry (exponential backoff capped at 8s, and no new attempt started more than 60s after the first — see oidcRetry), and callMint retries up to 5 times (1s+2s+4s+8s backoff). Each HTTP round trip is individually bounded by httpClient's 30s timeout (see doWithRetryPolicy, fetchOIDCJWT, callMint).
The OIDC phase therefore ends within about 60s plus one attempt (at most 90s even if that final attempt hangs for the full client timeout), and callMint adds 15s of backoff on top. The literal worst case — every callMint attempt also hanging for the full 30s client timeout — is far longer, unrealistically long for a caller to wait out during teardown. In practice an 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 ~75s backoff-dominated estimate (a minute-long OIDC endpoint outage followed by a few mint retries), 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"`
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.