install

package
v0.57.1-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package install provides pool-repo lifecycle management for behaviour tests: cross-org repo slot leasing (slotpool.go), per-org mint deployment, fullsend installation, and teardown.

Credential context separation

Two distinct credential contexts operate on pool repos. Understanding this separation is essential when working on repo-readiness checks on freshly created slot repos.

The test suite holds an e2e GitHub App installation token, minted via OIDC at CI job start. This token drives all suite-side API calls: repo creation/deletion, label application, PR management, and the readiness-polling functions in this package (awaitCreation, awaitDeletion, awaitWorkflowReady).

Dispatch workflows (harness-dispatch, harness-run) operate with the pool repo's own GITHUB_TOKEN — a per-workflow-run token scoped to the repository where the workflow executes. This token is used by harness-dispatch to call GetCollaboratorPermission when authorizing the triggering actor.

These are independent credential contexts with independent permission propagation graphs. When a slot repo is deleted at release and created again by a later claim (slotpool.go), the suite's e2e token can observe the new repo via GetRepo (awaitCreation) as soon as the repo object propagates through GitHub's eventual-consistency layer. However, the dispatch-side GITHUB_TOKEN's view of collaborator permissions on the new repo ID propagates on a separate, slower schedule that the suite cannot observe or predict.

Consequence: the suite CANNOT reliably probe or wait for dispatch-side permission readiness by calling GetCollaboratorPermission from the suite side. The suite's e2e installation token and dispatch's GITHUB_TOKEN resolve permissions through different GitHub subsystems. Polling GetCollaboratorPermission with the suite's token tells you nothing about whether dispatch's token will see the correct permissions. This was empirically validated in issue #6701: both a human developer (PR #6703) and an autonomous agent (PR #6709) independently attempted suite-side permission polling with exponential backoff, and both failed — 0 of 12 repos resolved over 63 seconds.

Any fix for dispatch-side permission propagation delays on freshly recreated repos must operate on the dispatch side (e.g., retry within the dispatch workflow itself) rather than from the suite side.

Test actor access

Human-like test actors (fstest-write, fstest-triage) inherit write/triage access from GitHub organization-level all-repository roles, not from per-repo collaborator grants. Direct grants are deleted with the repo and re-adding them creates pending invitations (#7777). The ensurer verifies org membership once per org; it must not call AddCollaborator. The all-repository role itself is verified only by e2e/org-pool/setup-org.sh at setup time, not by the ensurer, so the e2e GitHub App installation does not need the organization_custom_roles permission. fstest-outsider must remain outside the organization.

openbao.go runs a feature-scoped OpenBao dev-mode server for the behaviour suite's Vault-backed runner secret scenarios (ADR 0155). Like the trace collector, the tested Fullsend workflows run on separate GitHub-hosted runners, so the server's API is published on the CI worker's loopback and exposed to them through a Cloudflare quick tunnel (TLS, which Vault connections require). The server authenticates the tested workflows with their job OIDC token through a JWT auth mount bound to the GitHub Actions issuer, the default Fullsend Vault audience and the leased repositories, and serves synthetic per-scenario KV v2 secrets under a dedicated prefix through a read-only policy. The random root token never leaves the CI worker: it reaches the container through podman's environment (never a command line) and is registered with the process redactor.

A feature that exercises Vault starts one server, reuses it across its scenarios and stops it at feature or job cleanup; features that do not exercise Vault never start it.

playback_driver.go implements PlaybackDriver, a playback-mode marker and delegating wrapper around a standard behaviour repo-pool Driver. Allocation, WIF resolution, installation, cleanup, and capacity all remain owned by the wrapped Driver — this keeps the existing pool-based driver paths untouched. The tracking-issue/comment setup playback scenarios rely on is provisioned separately via playbackInstallHooks, attached to the repoEnsurer by the factories (e.g. NewRepoPoolCFMintPreviews) alongside PlaybackDriver construction.

repopool_cfmint_previews.go implements the RepoPoolCFMintPreviews driver. It deploys a temporary Cloudflare Worker preview mint for behaviour tests and constructs a unified Driver that owns allocation, deallocation, ensure, and teardown.

The preview mint is self-contained: all configuration (PEMs, allowlists, provenance) is passed at deploy time. Teardown abandons the preview alias.

repopool_cfmint_stage.go implements the RepoPoolCFMintStage driver. It deploys a durable Cloudflare Worker mint at stage-mint.fullsend.sh and constructs a unified Driver that owns allocation, deallocation, ensure, and teardown. Unlike the preview driver, the durable Worker persists across runs — teardown is a no-op.

The STAGE driver uses non-vendored per-repo install mode with --fullsend-ref=main so that pool repos reference the latest code on the default branch instead of a vendored binary.

repopool_external_mint.go implements the RepoPoolExternalMint driver. It uses a pre-configured mint URL without deploying anything. This is the original install path retained for test configurations that use a pre-existing mint endpoint.

repopool_github_emulator.go implements the RepoPoolGitHubEmulator driver: the external-mint pool, run against a GitHub emulator (ENVIRONMENT=github-emulator).

slotgc.go reclaims abandoned slot repositories inside the allocator (#8621). A runner that crashes, or whose Release fails, leaves its slot repository behind, and every allocator then treats that slot as occupied. Without collection, repeated crashes would exhaust the pool.

Trigger: Claim counts, per org, the slots it finds occupied by another lease's repository in passes that leased nothing. Once an org reaches gcThresholdPasses full passes' worth of occupied claims (gcThresholdPasses × SlotsPerOrg), the pass tries to collect that org before returning its CapacityError, and the counter starts again. An org inside a rate-limit window is not collected (or probed) until the window ends.

Candidates: only the slot names derived from the pool layout are inspected. A repository is reclaimed only when it carries the test-ownership marker (SlotRepoDescription plus a well-formed lease nonce), has a known repository ID and creation time, is not archived, and is older than slotReclaimAge. Anything else (unmarked, young, unknown identity or age, a failed or throttled lookup) is left occupied and reported.

Age bound: slotReclaimAge is slotJobTimeLimit plus slotReclaimMargin. A slot repository is created by a claim and deleted by its Release, so it never outlives the process that claimed it. That process is the behaviour or playback suite, which `go test -timeout 45m` (Makefile) panics, bounding every claiming process — and so every claimed repository's life — at slotJobTimeLimit past the claim. The CI jobs' `timeout-minutes: 90` (.github/workflows/e2e.yml) exceeds that bound because the infra-retry wrapper (scripts/run-with-infra-retry.sh) re-runs an infrastructure- classified failed suite once, as a second sequential `go test` process after the first exits: each attempt keeps its own `-timeout`, and a job kill can only shorten a process, never extend a slot repository past the per-attempt bound. A Godog context deadline alone would not stop a step, so it is not the bound. The margin covers requests still in flight when a job is killed and clock skew between GitHub's creation time and the runner clock. TestSlotReclaimAgeCoversJobLimits fails if the per-attempt -timeout is raised past slotJobTimeLimit, or a job budget past the two attempts it may run.

Coordination: each org has one collector at a time across all suites. The collector lease is the file slotGCLeasePath in the persistent repository slotGCRepo, separate from the temporary e2e-lock bridge (orglock.go). It changes only through forge.Client.UpdateFileIfMatch, so a takeover, and a release, apply only against the state they read. A collector:

  1. reads the lease and skips the org while another collector's lease is unexpired or the last collection ended less than gcCooldown ago;
  2. inspects the slots read-only and stops if none is a candidate;
  3. writes its own lease (expiring after gcLeaseDuration) conditional on the SHA it read; a conflict means another collector won;
  4. before each delete, rereads the lease and acts only while the file is still exactly what it wrote and more than gcLeaseSafetyMargin of the lease remains, by both the lease's wall-clock expiry and the local monotonic clock; it then rereads the repository and deletes only if the ID, description and creation time are unchanged;
  5. releases the lease (recording the collection time) conditional on the SHA it wrote, so it can neither extend nor release a successor's lease.

A collector that crashes leaves its lease to expire; the next collector takes it over after gcLeaseDuration. Every request is bounded by claimCreateTimeout, far below gcLeaseSafetyMargin, so the last action a collector starts finishes before its lease can expire.

Residual risk: GitHub deletes repositories by name, and has neither a delete conditional on the repository ID nor one conditional on the lease. Between the final identity check and the DELETE (one round trip), a collector paused for longer than gcLeaseSafetyMargin could in principle still delete a repository recreated under the name after a successor reclaimed the slot. The delete is never replayed after an ambiguous failure, and before any rate-limit resend the lease and the identity are checked again, so client waits do not widen that window.

slotpool.go implements repo-level slot leasing across pool orgs (#8578). The pool is one set of (org, repo-name) slots whose names are derived from numeric indices rather than kept in a list. Creating a slot's repository claims it; an existing repository means another allocator (in this process or another suite) holds it, so it is skipped and never reset or deleted. Each org installation's GitHub rate-limit headers gate further claims there until the reported reset.

This file provides the allocation layer; the shared install driver (composed.go) leases through it for the behaviour and playback suite runners. Slots left behind by crashed runners are reclaimed from the claim path by the GC in slotgc.go. Until legacy runners that take the exclusive e2e-lock have drained, each lease also holds the org's e2e-lock in shared mode (orglock.go).

The ensurer (ensure.go) only installs into a slot repo this allocator created for the lease; it never creates, deletes or resets a slot repo, so the "occupied is never deleted" rule holds throughout provisioning.

trace_collector.go runs a job-scoped OpenTelemetry Collector for the behaviour suite. The tested Fullsend workflows run on separate GitHub-hosted runners, so the Collector's OTLP/HTTP receiver is published on the CI worker's loopback and exposed to them through a Cloudflare quick tunnel (TLS, no inbound address needed). A fresh random bearer token, required by the receiver, is delivered to each leased repository as the OTEL_EXPORTER_OTLP_TRACES_HEADERS secret next to the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable the reusable workflows already read. The preview mint driver starts the collector before deploying its mint and passes the same endpoint and token to `fullsend mint deploy`, so mint spans land in the same trace files as the workflow spans that called the mint. The Collector writes one JSONL file per trace ID; Finalize copies those files and the Collector log under BEHAVIOUR_ARTIFACT_DIR before the job's redaction and upload steps run.

Index

Constants

View Source
const (
	// PerRepoTriageWorkflow is the workflow path for per-repo triage.
	PerRepoTriageWorkflow = "fullsend.yaml"

	// PerRepoAgentWorkflow is the per-repo shim workflow that runs the agent.
	PerRepoAgentWorkflow = "fullsend.yaml"

	// PerRepoAgentArtifact is the upload-artifact name for triage output.
	PerRepoAgentArtifact = "fullsend-triage"

	// DefaultPoolSize is the number of test-repo-NN repos in a pool org.
	// Drivers use this as the default capacity when no override is set.
	DefaultPoolSize = 12

	// MintProbeHostRepoSuffix names the per-slot repository that hosts
	// the reusable mint-probe workflow of the GitHub mint scope
	// scenarios: test-repo-NN + suffix. The CF mint drivers list these
	// names in the mint's WORKFLOW_HOST_REPOS next to the pool repos, so
	// a workflow hosted there is an approved workflow host while staying
	// a different repository from the leased test-repo-NN that calls it.
	// The repositories themselves are created and deleted per scenario.
	MintProbeHostRepoSuffix = "-mint-host"

	// MintStatusTeamSlug is the slug of the team in each pool org (and
	// the STAGE org) whose members may call the mint's /v1/status with
	// a GitHub user token. The CF mint drivers deploy their mint with
	// --status-auth=oidc,github --status-github-group=ORG/<slug>; the
	// team itself is created by e2e/org-pool/setup-org.sh.
	MintStatusTeamSlug = "mint-status"
)
View Source
const (
	// StageMintCustomDomain is the custom domain for the STAGE mint.
	StageMintCustomDomain = "stage-mint.fullsend.sh"

	// StageMintURL is the HTTPS URL for the STAGE mint. This is the
	// custom domain URL used for github setup --mint-url.
	StageMintURL = "https://" + StageMintCustomDomain

	// StageMintWorkerName is the CF Worker script name for the STAGE mint.
	StageMintWorkerName = "stage-mint"

	// StageOrg is the GitHub org used for STAGE behaviour tests.
	// Unlike the DEV pool orgs (halfsend-01 … halfsend-22), the STAGE
	// driver uses a single org. Within this org, a repo pool is used
	// just like in the DEV drivers.
	StageOrg = "halfsend"
)
View Source
const (

	// DevPoolOrgCount is the number of numbered DEV pool orgs
	// (halfsend-01 … halfsend-22).
	DevPoolOrgCount = 22

	// SlotRepoDescription is the description prefix every claimed slot
	// repo is created with. It is the test-ownership marker: only repos
	// carrying it may ever be reclaimed by GC. Each claim appends a
	// unique " lease=<nonce>" suffix so the claimer can recognise its own
	// repo (see Claim and Release).
	SlotRepoDescription = "fullsend behaviour test slot"
)
View Source
const ForgejoDevCapacity = 2

ForgejoDevCapacity is the forgejo-dev driver's Capacity: the initial concurrent scenario and Forgejo Runner job capacity of the managed Forgejo stack.

Variables

View Source
var ErrPoolCapacityExhausted = errors.New("behaviour pool capacity exhausted")

ErrPoolCapacityExhausted reports that no slot could be claimed in a claim pass: every eligible slot was occupied, or its org was rate-limited, denied, or failing. Use errors.Is; the concrete error is a *CapacityError carrying the per-reason breakdown.

Functions

func AppSet added in v0.50.0

func AppSet() string

AppSet returns the GitHub App set the behaviour mints are deployed with: BEHAVIOUR_APP_SET, or "fullsend-test" when unset. Its role Apps have the slugs "<app set>-<role>", so a registered bot's login is "<app set>-<role>[bot]".

func CFMintDeployArgs added in v0.37.0

func CFMintDeployArgs(alias, workerName string, cfg cfmintConfig) []string

CFMintDeployArgs builds the CLI arguments for `fullsend mint deploy --platform=cloudflare`. Exported so unit tests can verify arg construction without shelling out.

The preview is public (--public, PER_REPO_WIF_REPOS=*), so --per-repo-wif-repos is never passed; the CLI rejects it next to --public. --workflow-host-repos is always passed (even when empty) so the CLI sees it as explicitly changed: omitted flags preserve existing Worker bindings, while explicitly-empty values clear them.

func CFMintTeardownArgs added in v0.37.0

func CFMintTeardownArgs(previewAlias, workerName string) []string

CFMintTeardownArgs builds the CLI arguments for `fullsend mint delete --platform=cloudflare`. Exported so unit tests can verify arg construction without shelling out.

func CFMintWorkerName added in v0.37.0

func CFMintWorkerName(suiteName string) string

CFMintWorkerName derives the CF Worker script name from a suite name. The name clearly indicates it is the e2e/BT worker for that suite.

func GenerateCFMintPreviewAlias added in v0.37.0

func GenerateCFMintPreviewAlias() (string, error)

GenerateCFMintPreviewAlias creates a unique preview alias for a BT run. Format: bt-<8-hex-chars> (e.g., bt-a1b2c3d4). The alias satisfies the CF preview alias validation: 2-63 lowercase alphanumeric or hyphens.

func ParseCFMintURLFromOutput added in v0.37.0

func ParseCFMintURLFromOutput(output string) string

ParseCFMintURLFromOutput extracts the mint URL printed by `fullsend mint deploy`. The CLI prints a line like:

Worker deployed at https://<alias>-<worker>.<subdomain>.workers.dev

This is the canonical way to obtain the preview URL from a deploy invocation; callers should not re-derive it because the correct workers.dev subdomain is only known at deploy time.

func PoolOrgName added in v0.49.0

func PoolOrgName(index int) string

PoolOrgName derives an org name from its index: 0 is "halfsend", n >= 1 is "halfsend-NN".

func PoolSlotName added in v0.49.0

func PoolSlotName(index int) string

PoolSlotName derives a slot repo name from its 1-based index.

func StageMintDeployArgs added in v0.43.0

func StageMintDeployArgs(cfg stageMintConfig) []string

StageMintDeployArgs builds the CLI arguments for a durable `fullsend mint deploy --platform=cloudflare` with a custom domain.

func ValidatePerRepoPostInstall added in v0.36.0

func ValidatePerRepoPostInstall(ctx context.Context, client forge.Client, org, repo string) error

ValidatePerRepoPostInstall checks that a per-repo install left the expected files and configuration in the target repo, with the standard "dummy" runtime.

func ValidatePerRepoPostInstallNonVendored added in v0.43.0

func ValidatePerRepoPostInstallNonVendored(ctx context.Context, client forge.Client, org, repo string) error

ValidatePerRepoPostInstallNonVendored checks that a non-vendored per-repo install left the expected workflow shim and config, with the standard "dummy" runtime. Unlike ValidatePerRepoPostInstall it does not require vendored assets (marker file and binary) because non-vendored installs reference a remote fullsend-ref instead.

func ValidatePerRepoPostInstallNonVendoredWithRuntime added in v0.45.0

func ValidatePerRepoPostInstallNonVendoredWithRuntime(ctx context.Context, client forge.Client, org, repo, expectedRuntime string, logf ...func(string, ...any)) error

ValidatePerRepoPostInstallNonVendoredWithRuntime is like ValidatePerRepoPostInstallNonVendored but accepts the expected runtime name and, like ValidatePerRepoPostInstallWithRuntime, an optional logf for files that became readable only after a retry.

func ValidatePerRepoPostInstallWithRuntime added in v0.45.0

func ValidatePerRepoPostInstallWithRuntime(ctx context.Context, client forge.Client, org, repo, expectedRuntime string, logf ...func(string, ...any)) error

ValidatePerRepoPostInstallWithRuntime is like ValidatePerRepoPostInstall but accepts the expected runtime name, so callers that install with a non-default runtime (e.g. "dummy-playback") can validate against it. An optional logf receives a line for each file that became readable only after a retry, with the attempt count and elapsed time.

Types

type CLIRunnerFunc added in v0.33.0

type CLIRunnerFunc func(binary, token string, args ...string) (string, error)

CLIRunnerFunc is the signature for running a fullsend CLI command. The default implementation is e2etest.TryRunCLI. Inject a custom function in tests to avoid shelling out.

type CapacityError added in v0.49.0

type CapacityError struct {
	// Occupied counts slots whose repository already existed.
	Occupied int
	// RateLimited maps each quota-gated org to when it may be retried.
	RateLimited map[string]time.Time
	// Denied maps orgs whose credentials or create calls were refused
	// (forbidden, no client) to the last such error.
	Denied map[string]error
	// Failed maps orgs that hit transient or unclassified API failures
	// to the last such error.
	Failed map[string]error
	// LockExcluded maps orgs whose e2e-lock did not admit a new holder
	// (legacy lock, shared lock too old or closing) to the reason.
	LockExcluded map[string]string
	// Reclaimed counts slots freed by GC at the end of the pass (see
	// slotgc.go); Acquire retries at once when it is positive.
	Reclaimed int
	// GC maps each org GC ran on (or deferred) at the end of the pass to
	// its outcome: what was reclaimed, what was left occupied and why.
	GC map[string]string
	// contains filtered or unexported fields
}

CapacityError is returned by a claim pass that leased nothing. It separates occupied slots from orgs skipped for quota, permission, or transient failures so the suite log says why capacity ran out.

func (*CapacityError) Error added in v0.49.0

func (e *CapacityError) Error() string

func (*CapacityError) Is added in v0.49.0

func (e *CapacityError) Is(target error) bool

Is lets errors.Is match ErrPoolCapacityExhausted.

type Driver

type Driver interface {
	// AllocateRepo leases a repo in the driver's single org and makes it
	// ready. Drivers that lease across orgs implement LeaseDriver and
	// fail this call; use AllocateLease on them.
	AllocateRepo(ctx context.Context) (repoName string, err error)

	// DeallocateRepo releases a repo returned by AllocateRepo. Errors on
	// unknown name or double-release.
	DeallocateRepo(ctx context.Context, repoName string) error

	// Finalize always tears down suite-scoped resources (e.g. preview
	// mint). If leases are still outstanding, it reclaims them (logging
	// the names), completes teardown, and returns an error so leaked
	// After-hooks fail CI without stranding resources.
	Finalize(ctx context.Context) error

	// Capacity is the max concurrent outstanding allocations (the
	// driver's real parallelism ceiling: every slot of the pool). Godog
	// concurrency is controlled separately by GODOG_CONCURRENCY. If
	// concurrency exceeds Capacity(), excess workers block while
	// allocating — the suite emits an advisory warning but does not fail.
	Capacity() int
}

Driver owns mint/environment lifecycle and test-repo allocation for behaviour tests. The suite constructs exactly one Driver via a Factory and threads it through World; scenarios lease a ready repo and release it after cleanup. Finalize tears down suite-scoped resources and reclaims any outstanding leases.

Implementations must be safe for concurrent use by multiple godog scenarios (GODOG_CONCURRENCY > 1).

func NewForgejoDev added in v0.57.0

func NewForgejoDev(PoolConfig) (Driver, error)

NewForgejoDev is the install Factory for ENVIRONMENT=forgejo-dev. It returns the stub driver; pool is ignored because the GitHub pool layout and credentials do not apply to Forgejo.

func NewRepoPoolCFMintPreviews added in v0.37.0

func NewRepoPoolCFMintPreviews(pool PoolConfig) (Driver, error)

NewRepoPoolCFMintPreviews is a Factory for the DEV pool. It returns the shared slot-leasing Driver, which packs the pool orgs into the fewest mint groups whose WORKFLOW_HOST_REPOS fits a Worker variable (planMintGroups), deploys one public CF preview mint per group the first time a slot in any of its orgs is leased, and tears each down once at Finalize.

Driver-specific config is read from env: PEMs from TEST_*_PEM env vars (materialized for each deploy and removed after it), suite name from BEHAVIOUR_SUITE_NAME (default "bt"), and app set from BEHAVIOUR_APP_SET (default "fullsend-test"). A group's workflow-host list is computed from its orgs and the layout's slots per org, and carries each slot's mint-probe host (see buildWorkflowHostRepoList). Every mint's status group is the mint-status team of one pool org, picked at random once per job.

func NewRepoPoolCFMintStage added in v0.43.0

func NewRepoPoolCFMintStage(pool PoolConfig) (Driver, error)

NewRepoPoolCFMintStage is a Factory for the STAGE pool: the single unsuffixed halfsend org (StagePoolLayout). It returns the shared slot-leasing Driver, which deploys the durable CF Worker mint at stage-mint.fullsend.sh when the first slot is leased.

The STAGE driver differs from the preview driver in three ways:

  • Deploys a durable (non-preview) Worker with a custom domain
  • Uses non-vendored per-repo install with --fullsend-ref=main
  • Teardown is a no-op (the durable Worker persists across runs)

The pool layout must contain exactly StageOrg ("halfsend"); the factory returns an error for any other layout.

func NewRepoPoolExternalMint added in v0.37.0

func NewRepoPoolExternalMint(pool PoolConfig) (Driver, error)

NewRepoPoolExternalMint is a Factory that returns the shared slot-leasing Driver backed by a pre-configured mint URL. Every org of the pool uses that mint, which must already enroll the pool's slot repos; nothing is deployed and teardown is a no-op.

The mint URL is read from FULLSEND_MINT_URL.

func NewRepoPoolGitHubEmulator

func NewRepoPoolGitHubEmulator(pool PoolConfig) (Driver, error)

NewRepoPoolGitHubEmulator is a Factory for a pool on a GitHub emulator. It is the external-mint pool (mint at FULLSEND_MINT_URL, nothing deployed, each slot installed vendored, App set from BEHAVIOUR_APP_SET) with one addition: the emulator starts empty, so the pool's orgs are created first when they do not exist, owned by the token's user.

The emulator's orgs belong to this suite alone, so the shared e2e-lock bridge to legacy runners is left out (PoolConfig.PrivateOrgs). Everything else is the live code path: slot creation, Actions-readiness polling, slot GC and the rate-limit gate run unchanged.

type Factory added in v0.37.0

type Factory func(pool PoolConfig) (Driver, error)

Factory constructs the suite's shared Driver over a pool of (org, repo-name) slots. Driver-specific inputs (PEMs, allowlists, mint URL) are read from env or computed per org; each org's mint is deployed the first time a slot in it is leased. Configuration a factory can check without deploying (e.g. PEMs present) fails the factory, before scenarios run.

type InstallHooks added in v0.45.0

type InstallHooks struct {
	BeforeInstall func(ctx context.Context, client forge.Client, org, repo string) (any, error)
	AfterInstall  func(ctx context.Context, client forge.Client, org, repo string, state any) error
}

InstallHooks lets a specialized driver (e.g. PlaybackDriver) run extra work around the standard install flow without duplicating it. BeforeInstall runs after repo creation but before github setup; its return value is threaded to AfterInstall, which runs after setup and post-install validation both succeed. Either func may be nil.

type LeaseDriver added in v0.50.0

type LeaseDriver interface {
	Driver

	// AllocateLease claims a free (org, repo) slot through the slot
	// allocator, deploys the org's mint if this is the org's first
	// lease, and installs fullsend into the slot repo the claim created.
	// Blocks until a slot is free or ctx is cancelled. A slot whose
	// install fails is released before the error is returned.
	AllocateLease(ctx context.Context) (RepoLease, error)

	// DeallocateLease releases a slot returned by AllocateLease: it
	// removes leftover per-slot state, then deletes the slot repo if it
	// is still this lease's (another holder's repository under the same
	// name is never deleted) and frees the slot. Errors on an unknown
	// slot or a double release. Called after scenario cleanup and debug
	// collection.
	DeallocateLease(ctx context.Context, org, repo string) error
}

LeaseDriver is a Driver that leases slots across pool orgs. Callers that know about it use AllocateLease and DeallocateLease, which carry the slot's org; the shared pool driver returns an error from AllocateRepo, since a repo name alone does not identify a slot.

type LeaseVerifier added in v0.50.0

type LeaseVerifier interface {
	// StillOwnsLease reports whether the repository currently under
	// (org, repo) is still the one this driver's lease claimed. It
	// changes no state. false means the repo is gone, was replaced, or
	// the lease is not outstanding; an error means ownership could not
	// be verified, which callers treat as not owned.
	StillOwnsLease(ctx context.Context, org, repo string) (bool, error)
}

LeaseVerifier is implemented by a LeaseDriver that can tell whether a slot it leased is still its caller's. Scenario cleanup mutates the repository and auxiliary repositories by name, and the name may have been taken over by another holder (for example after GC deleted a slow lessee's repo), so cleanup asks before each mutation and skips it when the answer is no or cannot be determined.

type MintURLReporter added in v0.48.0

type MintURLReporter interface {
	// MintURL returns the suite's mint URL, or "" when none is known.
	MintURL() string
}

MintURLReporter is an optional Driver interface reporting the URL of the mint the driver was configured with. It is separate from Driver so external Driver implementations keep compiling. A LeaseDriver reports each lease's mint in RepoLease.MintURL instead, since every org has its own mint; steps that need the mint address (the CLI mint status scenarios) use the lease's and fall back to this interface.

type OrgAccess added in v0.57.0

type OrgAccess struct {
	Org    string
	Token  string
	Client forge.Client
}

OrgAccess is the org, installation token and forge client the suite's template World uses before a scenario leases a slot. Every field is empty or nil for a driver that has no default org.

type OrgClientFunc added in v0.49.0

type OrgClientFunc func(ctx context.Context, org string) (forge.Client, error)

OrgClientFunc returns the forge client holding org's credentials (its own installation token). Clients that implement forge.RateLimitReporter feed the per-org rate-limit gate. It is called again by Release, because installation tokens expire after an hour and a lease can outlive the claim-time token; it must return a client whose credentials are valid at call time (refreshing or re-minting as needed).

type OrgTokenFunc added in v0.50.0

type OrgTokenFunc func(ctx context.Context, org string) (string, error)

OrgTokenFunc returns an installation token for org: the e2e GitHub App installation token minted for that org in CI, or the developer's own token locally. It is called at most once per org per suite (see PoolConfig.TokenFor).

type OwnerCheck added in v0.50.0

type OwnerCheck func(ctx context.Context) (bool, error)

OwnerCheck reports whether the repository under a slot's name is still the one its lease claimed. It changes no state. A nil OwnerCheck means the caller holds the slot and needs no verification.

type PlaybackDriver added in v0.45.0

type PlaybackDriver struct {
	// contains filtered or unexported fields
}

PlaybackDriver is a playback-mode marker and delegating wrapper around a standard behaviour repo-pool Driver: World.IsPlaybackMode type-asserts on it to detect a playback suite, and it forwards AllocateRepo/DeallocateRepo/Finalize/Capacity unchanged to the wrapped Driver. The tracking-issue/comment setup playback installs rely on is provisioned by playbackInstallHooks, attached to the repoEnsurer independently of this wrapper.

func NewPlaybackDriver added in v0.45.0

func NewPlaybackDriver(base Driver) *PlaybackDriver

NewPlaybackDriver wraps a standard behaviour Driver for playback tests. base is typically constructed by one of the existing Factory functions (e.g. NewRepoPoolCFMintPreviews, NewRepoPoolCFMintStage) using GitHubSetupOpts.Runtime set to "dummy-playback" so installed repos run the playback runtime; playbackInstallHooks (attached to the ensurer by the same factory) provisions the tracking-issue bookkeeping those installs rely on.

func (*PlaybackDriver) AllocateLease added in v0.50.0

func (d *PlaybackDriver) AllocateLease(ctx context.Context) (RepoLease, error)

AllocateLease delegates to the wrapped Driver when it is a LeaseDriver, so playback scenarios lease cross-org slots through the same allocator as the behaviour suite. For any other Driver it falls back to AllocateRepo and returns a lease with only Repo set; the caller keeps its own org.

func (*PlaybackDriver) AllocateRepo added in v0.45.0

func (d *PlaybackDriver) AllocateRepo(ctx context.Context) (string, error)

AllocateRepo delegates to the wrapped Driver.

func (*PlaybackDriver) Capacity added in v0.45.0

func (d *PlaybackDriver) Capacity() int

Capacity delegates to the wrapped Driver.

func (*PlaybackDriver) DeallocateLease added in v0.50.0

func (d *PlaybackDriver) DeallocateLease(ctx context.Context, org, repo string) error

DeallocateLease delegates to the wrapped Driver when it is a LeaseDriver, and to DeallocateRepo otherwise.

func (*PlaybackDriver) DeallocateRepo added in v0.45.0

func (d *PlaybackDriver) DeallocateRepo(ctx context.Context, repoName string) error

DeallocateRepo delegates to the wrapped Driver.

func (*PlaybackDriver) DefaultConcurrency added in v0.57.0

func (d *PlaybackDriver) DefaultConcurrency() int

DefaultConcurrency delegates to the wrapped Driver's SuiteBootstrap.

func (*PlaybackDriver) DefaultOrg added in v0.57.0

func (d *PlaybackDriver) DefaultOrg(ctx context.Context) (OrgAccess, error)

DefaultOrg delegates to the wrapped Driver's SuiteBootstrap.

func (*PlaybackDriver) Describe added in v0.57.0

func (d *PlaybackDriver) Describe() string

Describe delegates to the wrapped Driver's SuiteBootstrap.

func (*PlaybackDriver) Finalize added in v0.45.0

func (d *PlaybackDriver) Finalize(ctx context.Context) error

Finalize delegates to the wrapped Driver.

func (*PlaybackDriver) SetRepoHint added in v0.45.0

func (d *PlaybackDriver) SetRepoHint(string)

SetRepoHint is retained for the shared playback step definitions. Pool repositories have stable names assigned by the wrapped Driver, so the hint is not used to influence allocation.

func (*PlaybackDriver) StillOwnsLease added in v0.50.0

func (d *PlaybackDriver) StillOwnsLease(ctx context.Context, org, repo string) (bool, error)

StillOwnsLease delegates to the wrapped Driver when it is a LeaseVerifier. A wrapped LeaseDriver that cannot verify is reported as an error (not owned); a wrapped Driver that leases by repo name alone has no shared slots to lose, so it owns its lease.

type PoolConfig added in v0.50.0

type PoolConfig struct {
	// Layout is the pool's orgs and slots (see PoolLayoutForEnvironment).
	Layout PoolLayout
	// TokenFor returns an org's installation token. The driver calls it
	// once per org and keeps the token for the rest of the suite: an
	// installation token lives an hour, longer than the suite's job time
	// limit (slotJobTimeLimit), so a token minted at any point of the run
	// is still valid at its end.
	TokenFor OrgTokenFunc
	// NewClient builds a forge client from a token (e.g.
	// e2etest.NewLiveClient). One client is built per org, so the
	// allocator's per-org rate-limit gate also sees the requests the
	// org's scenarios make with it.
	NewClient func(token string) forge.Client
	// Binary is the fullsend CLI built for the suite.
	Binary string
	// GCPProjectID is the inference GCP project ("" skips inference).
	GCPProjectID string
	// Logf is the suite logger.
	Logf func(string, ...any)
	// PrivateOrgs reports that no other suite runner leases the pool's
	// orgs (a GitHub emulator started for this suite). The shared
	// e2e-lock bridge to legacy runners (orglock.go) is then left out:
	// with no legacy runner to keep out, its admission window only drains
	// every worker once the lock is 15 minutes old.
	PrivateOrgs bool
}

PoolConfig is the input of a Factory: the pool to lease from and the suite's runtime dependencies.

type PoolLayout added in v0.49.0

type PoolLayout struct {
	// FirstOrgIndex is the index of the first org. 0 selects the
	// unsuffixed STAGE org; DEV starts at 1.
	FirstOrgIndex int
	// OrgCount is the number of consecutive org indices in the pool.
	OrgCount int
	// SlotsPerOrg is the number of test-repo-NN slots in each org.
	SlotsPerOrg int
}

PoolLayout describes the pool's orgs and slots by numeric index. Names are derived by PoolOrgName and PoolSlotName.

func DevPoolLayout added in v0.49.0

func DevPoolLayout(slotsPerOrg int) PoolLayout

DevPoolLayout is the DEV pool: halfsend-01 … halfsend-22, each with test-repo-01 … test-repo-<slotsPerOrg> (DefaultPoolSize by default).

func PoolLayoutForEnvironment added in v0.49.0

func PoolLayoutForEnvironment(environment string, logf func(string, ...any)) PoolLayout

PoolLayoutForEnvironment returns StagePoolLayout for "stage" and "github-emulator" (one org, which the github-emulator factory creates), and DevPoolLayout otherwise, matching the install factory selection. The slot count honours BEHAVIOUR_POOL_SIZE through envPoolSize, the same source as the mint and WIF repo lists, so the allocator never claims a test-repo-NN name that has no mint/WIF configuration. logf receives the warning for an unparsable override and may be nil.

func StagePoolLayout added in v0.49.0

func StagePoolLayout(slotsPerOrg int) PoolLayout

StagePoolLayout is the STAGE pool: the single unsuffixed halfsend org with test-repo-01 … test-repo-<slotsPerOrg>.

func (PoolLayout) Orgs added in v0.49.0

func (l PoolLayout) Orgs() []string

Orgs returns the layout's org names in index order.

func (PoolLayout) Slots added in v0.49.0

func (l PoolLayout) Slots() []Slot

Slots returns every (org, repo) slot of the layout in index order.

type RepoLease added in v0.50.0

type RepoLease struct {
	Org     string
	Repo    string
	Token   string
	Client  forge.Client
	MintURL string

	// MintStatusGroup is the ORG/TEAM the mint was deployed with as
	// --status-github-group: one pool org's mint-status team, picked
	// once per job and shared by every mint. It need not be the lease's
	// org. Empty when the driver does not configure status auth.
	MintStatusGroup string
	// MintWorkflowHostRepos is the mint's WORKFLOW_HOST_REPOS: every
	// workflow host of the mint group serving the lease's org. Nil when
	// the driver does not configure the mint's workflow hosts.
	MintWorkflowHostRepos []string
}

RepoLease is one leased pool slot and everything a scenario needs to operate on it: the slot's org and repo, that org's installation token and the forge client built from it, and the URL of the mint serving the org. A scenario's World, SCM and CI drivers, mint configuration, and cleanup all use this org.

type SettleFunc added in v0.33.0

type SettleFunc func(ctx context.Context, client forge.Client, org, repo, workflowFile string, logf func(string, ...any)) error

SettleFunc is called after a repo is freshly created or installed to wait until GitHub Actions recognises the workflow file. The default implementation polls GetWorkflow; tests inject a no-op. An error wrapping errWorkflowNotReady makes AllocateLease claim a fresh repo.

type Slot added in v0.49.0

type Slot struct {
	Org  string
	Repo string
}

Slot is one (org, repo-name) pool position.

func (Slot) String added in v0.49.0

func (s Slot) String() string

String renders the slot as org/repo.

type SuiteBootstrap added in v0.57.0

type SuiteBootstrap interface {
	// DefaultConcurrency is the godog worker count when GODOG_CONCURRENCY
	// is unset. The runner caps it at Capacity.
	DefaultConcurrency() int

	// Describe is a one-line description of what the driver allocates
	// from, for the suite log.
	Describe() string

	// DefaultOrg returns the org, token and client the template World
	// points at until a scenario leases a slot. An error means the run
	// cannot start.
	DefaultOrg(ctx context.Context) (OrgAccess, error)
}

SuiteBootstrap is an optional Driver interface. It supplies the details the suite runner needs before scenarios start, so the runner never reads a driver's pool layout or calls its token source itself. It is separate from Driver so external Driver implementations keep compiling. Use BootstrapFor to get it for any Driver.

func BootstrapFor added in v0.57.0

func BootstrapFor(d Driver) SuiteBootstrap

BootstrapFor returns d's SuiteBootstrap. A Driver that does not implement it gets a fallback: the default concurrency is Capacity, the description names the driver type, and there is no default org (an empty OrgAccess). The fallback never mints a token or builds a client.

type VaultServer

type VaultServer interface {
	// Address is the HTTPS URL the tested workflows reach the server at;
	// it belongs in trusted base configuration as vault_address.
	Address() string
	// AllowRepo lets org/repo's workflows log in with the default
	// Fullsend Vault role and audience.
	AllowRepo(ctx context.Context, org, repo string) error
	// PutSecret writes a synthetic secret and returns its KV v2 read
	// path for vault_secrets.
	PutSecret(ctx context.Context, name string, data map[string]string) (string, error)
	// Stop stops and removes the server. Safe to call more than once.
	Stop(ctx context.Context) error
}

VaultServer is a running feature-scoped OpenBao server, as the Vault feature steps see it.

func StartVaultServer

func StartVaultServer(logf func(string, ...any)) (server VaultServer, skip string, err error)

StartVaultServer starts the OpenBao server for a Vault feature when the environment enables the Vault scenarios. It returns a nil server and a non-empty skip reason when they are disabled or a prerequisite is missing (outside GitHub Actions, or without podman), so local runs can skip them. Unlike the trace collector, a start failure is returned: the feature's scenarios cannot run without the server. When the failed start's own cleanup also failed, the partially started server is returned with the error, so the caller can retry Stop at feature or job cleanup; otherwise the server is nil.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL