install

package
v0.46.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package install provides pool-repo lifecycle management for behaviour tests: lazy repo creation, fullsend installation, pool leasing, and teardown.

Credential context separation

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

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 pool repo is deleted and recreated (resetRepo), 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 hack/setup-new-e2e-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.

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.

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
)
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-12), the STAGE
	// driver uses a single org. Within this org, a repo pool is used
	// just like in the DEV drivers.
	StageOrg = "halfsend"
)

Variables

This section is empty.

Functions

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.

--per-repo-wif-repos and --workflow-host-repos are always passed (even when empty) so the CLI sees them as explicitly changed. The CLI uses "flag changed" semantics: 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 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) error

ValidatePerRepoPostInstallNonVendoredWithRuntime is like ValidatePerRepoPostInstallNonVendored but accepts the expected runtime name.

func ValidatePerRepoPostInstallWithRuntime added in v0.45.0

func ValidatePerRepoPostInstallWithRuntime(ctx context.Context, client forge.Client, org, repo, expectedRuntime string) 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.

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 Driver

type Driver interface {
	// AllocateRepo leases a slot and makes that repo ready (delete and
	// recreate if it already exists, then install). Blocks until a slot
	// is free or ctx is cancelled. Returns the repo name only (org is
	// fixed for the driver / World).
	AllocateRepo(ctx context.Context) (repoName string, err error)

	// DeallocateRepo deletes the leased repository (best-effort) and
	// returns the name to the pool. Errors on unknown name or
	// double-release. Called after scenario cleanup and debug
	// collection so leftover base-repo state cannot leak to the next
	// lessee.
	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). Suite may default concurrency
	// to Capacity() or honor GODOG_CONCURRENCY. If concurrency exceeds
	// Capacity(), excess workers block in AllocateRepo — 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 call AllocateRepo to lease a ready repo and DeallocateRepo to delete it and return the name. 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 NewRepoPoolCFMintPreviews added in v0.37.0

func NewRepoPoolCFMintPreviews(
	org string,
	client forge.Client,
	token, binary, gcpProjectID string,
	logf func(string, ...any),
) (Driver, error)

NewRepoPoolCFMintPreviews is a Factory that deploys a CF preview mint and returns a unified Driver owning allocation, deallocation, ensure, and teardown.

Driver-specific config is read from env: PEM dir from TEST_*_PEM env vars (materialized internally), suite name from BEHAVIOUR_SUITE_NAME (default "bt"), and app set from BEHAVIOUR_APP_SET (default "fullsend-test"). Pool size defaults to DefaultPoolSize. WIF and workflow-host repo lists are computed from the org and pool size.

func NewRepoPoolCFMintStage added in v0.43.0

func NewRepoPoolCFMintStage(
	org string,
	client forge.Client,
	token, binary, gcpProjectID string,
	logf func(string, ...any),
) (Driver, error)

NewRepoPoolCFMintStage is a Factory that deploys a durable CF Worker mint at stage-mint.fullsend.sh and returns a unified Driver owning allocation, deallocation, ensure, and teardown for the halfsend org.

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 org parameter must equal StageOrg ("halfsend"); the driver returns an error if a different org is passed.

func NewRepoPoolExternalMint added in v0.37.0

func NewRepoPoolExternalMint(
	org string,
	client forge.Client,
	token, binary, gcpProjectID string,
	logf func(string, ...any),
) (Driver, error)

NewRepoPoolExternalMint is a Factory that returns a unified Driver backed by a pre-configured mint URL. The driver uses the existing mint without deploying anything; teardown is a no-op.

The mint URL is read from FULLSEND_MINT_URL. Pool size defaults to DefaultPoolSize (overridable via BEHAVIOUR_POOL_SIZE).

type Factory added in v0.37.0

type Factory func(
	org string,
	client forge.Client,
	token, binary, gcpProjectID string,
	logf func(string, ...any),
) (Driver, error)

Factory constructs a unified Driver for a given org. The factory performs suite setup (e.g. preview mint deploy) before returning so setup failures fail the suite before scenarios run.

All driver-specific inputs (PEMs, allowlists, mint URL, pool size) are read from env or computed from the org inside the factory. Runtime dependencies (forge client, token, CLI binary, GCP project, logger) are passed as parameters.

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 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) 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) DeallocateRepo added in v0.45.0

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

DeallocateRepo delegates to the wrapped Driver.

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.

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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