Help us shape the future of Go! Take the 2026 Go Developer Survey

gcpcloudbuild

package
v1.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: MIT Imports: 54 Imported by: 0

README

Cloud Build

Parity grade: B · SDK cloud.google.com/go/cloudbuild@v1.34.0 · last audited 2026-10-22 (1c0729588)

Coverage

Metric Value
PARITY entries audited 20 (20 ok)
Feature families 13 (10 ok, 3 partial)
Known gaps 11
Deferred items 0
Resource leaks ok
Known gaps
  • connectedRepository and storageSourceManifest builds fail with FETCH_SOURCE_FAILED; repoSource branch_name is a literal ref, not a regex; repository_event_config and git_file_source triggers cannot resolve a repository, and triggers that read cloudbuild.yaml from a repository can be stored but not run.
  • Event triggers on repository events (trigger_template, github, repository_event_config) are stored and never fire, because the emulator has no repository event source; builds start from CreateBuild, RetryBuild, RunBuildTrigger, ReceiveTriggerWebhook and pubsub_config triggers. pubsub_config.subscription is not populated because no subscription is created, so $(body.subscription) is empty, and webhook and pubsub filters support only ==, !=, &&, ||, !, parentheses and matches/contains/startsWith/endsWith over substitution variables.
  • KMS-encrypted secrets and automap_substitutions are not supported.
  • options.pool, machine_type and disk_size_gb do not change where or how steps run, and queue_ttl never expires a build.
  • results.build_step_images, build_step_outputs, source_provenance file hashes, warnings and the FETCHSOURCE/PUSH timing entries are not populated; only the BUILD timing, step timing and artifact timing are.
  • Artifacts other than artifacts.objects (Maven, Python, npm, Go modules) are not uploaded because the Artifact Registry emulator only stores Docker images, and artifacts.images is not honoured beyond images.
  • Images can only be pushed to the Artifact Registry emulator; gcr.io and other registries fail the build.
  • Step containers share the host Docker daemon (and its socket when present), so builds are not isolated from each other or from the host.
  • Locations are path parameters only: the v1 API has no ListLocations, and any location id is accepted.
  • Authentication is not checked, IAM is not enforced and service_account is ignored.
  • No dashboard page.

More

Documentation

Overview

Package gcpcloudbuild emulates Google Cloud Build: the v1 API (builds, build triggers and worker pools) over gRPC and REST. Build steps run as containers with a shared /workspace; see PARITY.md.

Index

Constants

View Source 
const (
	// DefaultPort is the dedicated gRPC and REST listener's default TCP port.
	DefaultPort = 8136
	// EngineAuto runs build steps as containers when a container runtime is reachable.
	EngineAuto = "auto"
	// EngineNone never runs a container: builds are recorded and then fail with a clear status detail.
	EngineNone = "none"
)
View Source 
const (
	// DefaultGitImage is the image git fetches run in when Services.GitImage is empty.
	DefaultGitImage = "alpine/git:latest"
)

Variables

View Source 
var ErrNilAppContext = errors.New("gcpcloudbuild: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

Functions

This section is empty.

Types

type API 

type API struct {
	cloudbuildpb.CloudBuildServer
	// contains filtered or unexported fields
}

API exposes the Cloud Build service plus stored build logs for in-process callers (dashboard proxy).

func (*API) BuildLog 

func (a *API) BuildLog(build *cloudbuildpb.Build) ([]byte, bool)

BuildLog returns the build's log from its logs bucket; ok is false when it has not been stored (yet).

type ConfigProvider 

type ConfigProvider interface {
	GetGCPCloudBuildSettings() Settings
}

ConfigProvider extracts Cloud Build configuration from the AppContext Config.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port int
	// contains filtered or unexported fields
}

Handler serves Cloud Build on a dedicated listener.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port from Settings.

func (*Handler) API 

func (h *Handler) API() *API

API returns the in-process Cloud Build API.

func (*Handler) Addr 

func (h *Handler) Addr() string

Addr returns the bound listener address, or "" before StartWorker.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(*echo.Context) string

ExtractOperation is unused: requests never reach the shared router.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(*echo.Context) string

ExtractResource is unused: requests never reach the shared router.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the supported gRPC methods.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns a 404 handler; the real API is on the dedicated port.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all in-memory state.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: Cloud Build runs on its own listener.

func (*Handler) Shutdown 

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the server, forcing a close after a short grace period.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated listener synchronously so a port conflict is returned to the caller.

type InMemoryBackend 

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

InMemoryBackend holds builds, triggers and worker pools under one lock and runs builds as containers.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend with no container runtime.

func (*InMemoryBackend) ApproveBuild 

func (b *InMemoryBackend) ApproveBuild(
	in *cloudbuildpb.ApproveBuildRequest,
) (*longrunningpb.Operation, error)

ApproveBuild records an approval decision on a build that awaits one.

func (*InMemoryBackend) CancelBuild 

func (b *InMemoryBackend) CancelBuild(
	in *cloudbuildpb.CancelBuildRequest,
) (*cloudbuildpb.Build, error)

CancelBuild cancels a queued, pending or running build.

func (*InMemoryBackend) Close 

func (b *InMemoryBackend) Close()

Close cancels running builds and waits for them to exit.

func (*InMemoryBackend) CreateBuild 

func (b *InMemoryBackend) CreateBuild(
	in *cloudbuildpb.CreateBuildRequest,
) (*longrunningpb.Operation, error)

CreateBuild queues a build.

func (*InMemoryBackend) CreateBuildTrigger 

func (b *InMemoryBackend) CreateBuildTrigger(
	in *cloudbuildpb.CreateBuildTriggerRequest,
) (*cloudbuildpb.BuildTrigger, error)

CreateBuildTrigger stores a trigger.

func (*InMemoryBackend) CreateWorkerPool 

func (b *InMemoryBackend) CreateWorkerPool(
	in *cloudbuildpb.CreateWorkerPoolRequest,
) (*longrunningpb.Operation, error)

CreateWorkerPool stores a worker pool; the pool is RUNNING when the operation completes.

func (*InMemoryBackend) DeleteBuildTrigger 

func (b *InMemoryBackend) DeleteBuildTrigger(in *cloudbuildpb.DeleteBuildTriggerRequest) error

DeleteBuildTrigger removes a trigger.

func (*InMemoryBackend) DeleteWorkerPool 

func (b *InMemoryBackend) DeleteWorkerPool(
	in *cloudbuildpb.DeleteWorkerPoolRequest,
) (*longrunningpb.Operation, error)

DeleteWorkerPool removes a worker pool; a stale etag aborts the call.

func (*InMemoryBackend) DisableEngine 

func (b *InMemoryBackend) DisableEngine(reason string)

DisableEngine records why builds cannot run; builds then fail with this status detail.

func (*InMemoryBackend) GetBuild 

func (b *InMemoryBackend) GetBuild(in *cloudbuildpb.GetBuildRequest) (*cloudbuildpb.Build, error)

GetBuild returns a build by name or by project_id and id.

func (*InMemoryBackend) GetBuildTrigger 

func (b *InMemoryBackend) GetBuildTrigger(
	in *cloudbuildpb.GetBuildTriggerRequest,
) (*cloudbuildpb.BuildTrigger, error)

GetBuildTrigger returns a trigger by name or by project_id and trigger_id.

func (*InMemoryBackend) GetWorkerPool 

func (b *InMemoryBackend) GetWorkerPool(name string) (*cloudbuildpb.WorkerPool, error)

GetWorkerPool returns a worker pool.

func (*InMemoryBackend) HandlePubsubMessage 

func (b *InMemoryBackend) HandlePubsubMessage(
	topic string, data []byte, attrs map[string]string, id string, published time.Time,
)

HandlePubsubMessage starts a build for every enabled pubsub_config trigger subscribed to topic ("projects/p/topics/t"). The trigger's $(body...) bindings see the message as Pub/Sub delivers it to a push endpoint: {"message": {"data": <base64>, "attributes": {...}, "messageId", "publishTime"}, "subscription"}.

func (*InMemoryBackend) ListBuildTriggers 

func (b *InMemoryBackend) ListBuildTriggers(
	in *cloudbuildpb.ListBuildTriggersRequest,
) ([]*cloudbuildpb.BuildTrigger, string, error)

ListBuildTriggers lists the triggers of a project and location ordered by creation time.

func (*InMemoryBackend) ListBuilds 

func (b *InMemoryBackend) ListBuilds(
	in *cloudbuildpb.ListBuildsRequest,
) ([]*cloudbuildpb.Build, string, error)

ListBuilds lists builds of a project and location, newest first.

func (*InMemoryBackend) ListWorkerPools 

func (b *InMemoryBackend) ListWorkerPools(
	in *cloudbuildpb.ListWorkerPoolsRequest,
) ([]*cloudbuildpb.WorkerPool, string, error)

ListWorkerPools lists the worker pools of a location ordered by name.

func (*InMemoryBackend) ReceiveTriggerWebhook 

func (b *InMemoryBackend) ReceiveTriggerWebhook(
	in *cloudbuildpb.ReceiveTriggerWebhookRequest,
) error

ReceiveTriggerWebhook runs a webhook trigger after checking the URL secret.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset cancels running builds and drops all state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads a snapshot. Builds that were queued or running when it was taken ended with the old process and are marked INTERNAL_ERROR.

func (*InMemoryBackend) RetryBuild 

func (b *InMemoryBackend) RetryBuild(
	in *cloudbuildpb.RetryBuildRequest,
) (*longrunningpb.Operation, error)

RetryBuild queues a new build from the request that created the original.

func (*InMemoryBackend) RunBuildTrigger 

func (b *InMemoryBackend) RunBuildTrigger(
	in *cloudbuildpb.RunBuildTriggerRequest,
) (*longrunningpb.Operation, error)

RunBuildTrigger queues a build from a trigger's inline build template.

func (*InMemoryBackend) SetClock 

func (b *InMemoryBackend) SetClock(now func() time.Time, after timerFunc)

SetClock replaces the wall clock and the timeout timer, for tests.

func (*InMemoryBackend) SetContext 

func (b *InMemoryBackend) SetContext(ctx context.Context)

SetContext bounds the lifetime of build goroutines.

func (*InMemoryBackend) SetRuntime 

func (b *InMemoryBackend) SetRuntime(rt Runtime)

SetRuntime enables execution of build steps on rt.

func (*InMemoryBackend) SetServices 

func (b *InMemoryBackend) SetServices(s Services)

SetServices wires the Cloud Storage, Pub/Sub, Logging, Secret Manager and Artifact Registry seams.

func (*InMemoryBackend) SetWorkDir 

func (b *InMemoryBackend) SetWorkDir(dir string)

SetWorkDir sets the host directory build workspaces are created under.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises builds, triggers, worker pools and operations. Workspaces and containers of running builds are not part of it.

func (*InMemoryBackend) UpdateBuildTrigger 

func (b *InMemoryBackend) UpdateBuildTrigger(
	in *cloudbuildpb.UpdateBuildTriggerRequest,
) (*cloudbuildpb.BuildTrigger, error)

UpdateBuildTrigger replaces a trigger, or only the masked fields when update_mask is set.

func (*InMemoryBackend) UpdateWorkerPool 

func (b *InMemoryBackend) UpdateWorkerPool(
	in *cloudbuildpb.UpdateWorkerPoolRequest,
) (*longrunningpb.Operation, error)

UpdateWorkerPool applies the masked fields (all mutable fields when no mask is given).

func (*InMemoryBackend) Wait 

func (b *InMemoryBackend) Wait()

Wait blocks until every running build goroutine has exited.

type ObjectStore 

type ObjectStore interface {
	ReadObject(bucket, object string) ([]byte, error)
	WriteObject(bucket, object string, data []byte, contentType string) error
	// EnsureBucket creates bucket under project when it does not exist.
	EnsureBucket(project, bucket string) error
}

ObjectStore reads and writes Cloud Storage objects in the emulator.

type Provider 

type Provider struct{}

Provider implements service.Provider for Google Cloud Build. It serves gRPC and REST on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init creates the backend and handler; the port is bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type Publisher 

type Publisher interface {
	Publish(project, topic string, data []byte, attrs map[string]string) error
}

Publisher publishes a message to a Pub/Sub topic of a project, creating the topic when missing.

type Runtime 

type Runtime interface {
	CreateAndStart(ctx context.Context, spec container.Spec) (string, error)
	StopAndRemove(ctx context.Context, containerID string) error
}

Runtime is the slice of the container runtime a build needs. The runtime must also implement container.ExitWaiter; it should implement container.LogStreamer (step output) and container.ImagePusher (images:).

type SecretResolver 

type SecretResolver interface {
	AccessSecret(versionName string) ([]byte, error)
}

SecretResolver reads a Secret Manager secret version ("projects/p/secrets/s/versions/v").

type Services 

type Services struct {
	Store   ObjectStore
	Pub     Publisher
	Secrets SecretResolver
	Logs    gcpserve.LogSink
	// RegistryAddr is the Artifact Registry emulator's host:port as the docker daemon reaches it.
	RegistryAddr string
	// GitImage runs git for gitSource and repoSource; empty uses DefaultGitImage.
	GitImage string
	// RepoBase is the base URL (http, https or file) repoSource repo_names resolve under as
	// <RepoBase>/<project>/<repo>; empty uses Cloud Source Repositories' address.
	RepoBase string
}

Services are the emulator backends a build reads from and writes to.

type Settings 

type Settings struct {
	Engine string `` //nolint:lll // config struct tags are intentionally verbose
	/* 225-byte string literal not displayed */
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 199-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI command as CLI.GCPCloudBuild.

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.