Documentation
¶
Overview ¶
Package gitcreds leases the credential a git workspace fetch needs.
It sits between pkg/secretbroker, which knows about grants and constraints, and the executor drivers, which know about Pods and edge devices and must not know about either. The drivers see executor.WorkspaceCredentialSource — an interface with no broker types in it — so a driver can be tested with a fake source, and so pkg/executor stays a leaf package that a remote agent can depend on without pulling in the hub's secret store.
Why the lease is taken by the driver and not by the caller ¶
The obvious alternative is for the Web UI to lease the token and put it in the Spec. It cannot: a Spec is persisted by pkg/executorstore, marshalled across the remote-executor boundary, and echoed into audit rows. A credential placed there would be durable in three places by the time anything used it.
So the Spec carries only the *name* of a grant, and the driver dispatching the workload leases the material at the last possible moment, holds it for the length of one fetch, and releases it. The credential's lifetime is a property of the code path rather than of anyone remembering to wipe it.
Index ¶
- type BrokerSource
- func (s *BrokerSource) ForProxiedWorkspace(ctx context.Context, projectID string, w executor.Workspace) (executor.WorkspaceAccess, func(), error)
- func (s *BrokerSource) ForWorkspace(ctx context.Context, projectID string, w executor.Workspace) (executor.WorkspaceAccess, func(), error)
- func (s *BrokerSource) LeasesRecorded() bool
- func (s *BrokerSource) RefreshWorkspaceCredential(ctx context.Context, cred executor.GitCredential, held string) (executor.GitCredential, func(), error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BrokerSource ¶
type BrokerSource struct {
// Broker is the control plane's secret broker.
Broker *secretbroker.Broker
// ExecutorID is the subject grants are matched against.
ExecutorID string
// Actor is the audit-trail identity for the lease.
Actor string
}
BrokerSource leases workspace credentials from a secret broker.
func New ¶
func New(broker *secretbroker.Broker, executorID, actor string) (*BrokerSource, error)
New returns a source, or an error when it would be unusable.
func (*BrokerSource) ForProxiedWorkspace ¶ added in v0.0.3
func (s *BrokerSource) ForProxiedWorkspace(ctx context.Context, projectID string, w executor.Workspace) (executor.WorkspaceAccess, func(), error)
ForProxiedWorkspace is ForWorkspace for a caller that will hand the credential to cloop's git proxy rather than to the executor — the gitproxycreds decorator, which looks for this method.
The difference is one fact told to the broker (Requester.GitHubProxied): a grant limited to certain branches keeps its push, because the proxy is what holds the push to the list. Leased through plain ForWorkspace the same grant is delivered without its push, since the credential is headed somewhere nothing can.
func (*BrokerSource) ForWorkspace ¶
func (s *BrokerSource) ForWorkspace(ctx context.Context, projectID string, w executor.Workspace) (executor.WorkspaceAccess, func(), error)
ForWorkspace implements executor.WorkspaceCredentialSource.
The returned release function is always non-nil, including on the error paths, so a caller can defer it unconditionally.
Selection is by *authority*, not by name alone. A grant satisfies the workspace when it is a GitHub credential whose repository allowlist admits this repository on the forge host its credential is good against — and, when the spec named a grant, when it is that one. A grant that names the right secret but excludes the repository is reported as a distinct Reason, because "create a grant" and "widen the grant you have" are different fixes and an operator who is told the wrong one will go looking in the wrong place.
A repository is (host, path) here (Task 20423). An allowlist names owner/name, so a grant for acme/* used to match https://attacker.example/acme/tool exactly as it matched github.com, and the token was handed to whatever host the project's origin named. Now a grant whose allowlist admits the path on another host is a refusal naming both hosts — never a credential, and never a silent pass.
func (*BrokerSource) LeasesRecorded ¶ added in v0.0.5
func (s *BrokerSource) LeasesRecorded() bool
LeasesRecorded implements gitproxycreds.RecordedSource: the broker records the leases it issues, so another hub process can take one over (Task 20390).
func (*BrokerSource) RefreshWorkspaceCredential ¶ added in v0.0.5
func (s *BrokerSource) RefreshWorkspaceCredential(ctx context.Context, cred executor.GitCredential, held string) (executor.GitCredential, func(), error)
RefreshWorkspaceCredential re-mints the GitHub App installation token cred carries, at the scope it was first minted at, for a git proxy session that presents it longer than GitHub's hour (Task 20375). held is the token the session presents now.
It returns the renewed credential and the function that destroys the one it replaced, which the session calls once nothing presents that any more. A refusal that will not change — the grant revoked or expired, the lease released, GitHub refusing for good — wraps executor.ErrCredentialRefused; any other error is worth retrying.
Source Files