ci

package
v1.223.0-rc.4 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// GroupModeAuto emits the finest grouping that applies to each command:
	// one group per workflow/custom-command step (DimensionStep) and one group
	// per phase of a terraform/helmfile/packer invocation (DimensionPhase).
	// This is the default when the mode is unset.
	GroupModeAuto = "auto"

	// GroupModeInvocation emits one group around each whole top-level
	// `atmos <command>` run (DimensionInvocation); finer step/phase grouping is
	// suppressed.
	GroupModeInvocation = "invocation"

	// GroupModeOff disables CI log grouping entirely.
	GroupModeOff = "off"
)

Grouping modes for ci.groups.mode. CI providers do not support nested groups, so the mode selects a single, mutually-exclusive granularity.

View Source 
const (
	AnnotationError   = provider.AnnotationError
	AnnotationWarning = provider.AnnotationWarning
	AnnotationNotice  = provider.AnnotationNotice
)

Re-exported annotation levels (see provider.AnnotationLevel).

View Source 
const (
	// CheckStatusStatePending indicates the check is pending or in progress.
	CheckStatusStatePending = provider.CheckStatusStatePending

	// CheckStatusStateSuccess indicates the check passed.
	CheckStatusStateSuccess = provider.CheckStatusStateSuccess

	// CheckStatusStateFailure indicates the check failed.
	CheckStatusStateFailure = provider.CheckStatusStateFailure

	// CheckStatusStateCancelled indicates the check was cancelled.
	CheckStatusStateCancelled = provider.CheckStatusStateCancelled

	// CheckStatusStateSkipped indicates the check was skipped.
	CheckStatusStateSkipped = provider.CheckStatusStateSkipped
)

Variables

This section is empty.

Functions

func Annotate added in v1.222.0 

func Annotate(annotations []Annotation) error

Annotate renders line-anchored annotations via the active CI provider when it implements the Annotator capability (GitHub Actions: `::error`/`::warning` shown inline on the PR diff). It is a no-op — returning nil — when no provider is detected or the detected provider is not an Annotator. Like WriteStepSummary, this is the seam non-CI subsystems (pkg/hooks scanner output) use to surface findings without depending on the internal provider types or any provider-specific env vars.

func ClearPlugins 

func ClearPlugins()

ClearPlugins removes all registered plugins. This is primarily for testing.

func Detect 

func Detect() provider.Provider

Detect returns a provider that detects it is active in the current environment.

func DetectCache added in v1.222.0 

func DetectCache() (cache.Backend, error)

DetectCache returns the cache backend exposed by the active CI provider. It returns errUtils.ErrCacheUnavailable when no CI provider is detected or the detected provider does not implement the cache capability. This keeps callers (CLI subcommands and lifecycle hooks) provider-agnostic.

DetectCache is the in-runner path: it requires the provider to be actively detected (e.g. GITHUB_ACTIONS=true), so the automatic restore/save lifecycle safely no-ops outside CI. For cache administration that should work locally, use ResolveAdminCache.

func DetectOrError 

func DetectOrError() (provider.Provider, error)

DetectOrError returns the detected provider or an error if none is detected.

func Execute 

func Execute(opts ExecuteOptions) error

Execute runs all CI actions for a hook event. Returns nil if not in CI or if the event is not handled.

func Get 

func Get(name string) (provider.Provider, error)

Get returns a provider by name.

func GetPlugin 

func GetPlugin(componentType string) (plugin.Plugin, bool)

GetPlugin returns a CI plugin by component type.

func GetPluginForEvent 

func GetPluginForEvent(event string) plugin.Plugin

GetPluginForEvent returns the plugin that handles a specific hook event. Returns nil if no plugin handles the event.

func Group added in v1.223.0 

func Group(atmosConfig *schema.AtmosConfiguration, dim Dimension, name string, fn func() error) error

Group runs fn wrapped in the detected CI provider's log-group markers, named `name`, when the configured mode selects the given dimension; otherwise it simply calls fn. The group-end marker is always emitted (even when fn returns an error or panics), so a failing operation never leaves a group open. Nested calls within the same process do not emit nested groups — only the outermost Group emits markers.

func GroupingEnabled added in v1.223.0 

func GroupingEnabled(atmosConfig *schema.AtmosConfiguration) bool

GroupingEnabled reports whether CI log grouping is available for this run in any dimension: a grouping mode other than "off" is configured, a grouping-capable provider is detected, and no parent Atmos process already has grouping open.

func IsCI 

func IsCI() bool

IsCI returns true if any CI provider is detected.

func IsCommitSHA added in v1.214.0 

func IsCommitSHA(s string) bool

IsCommitSHA returns true if s looks like a git commit SHA (7-40 hex chars).

func List 

func List() []string

List returns all registered provider names.

func ListPlugins 

func ListPlugins() []string

ListPlugins returns all registered plugin types.

func LogGroupSentinelEnv added in v1.223.0 

func LogGroupSentinelEnv() string

LogGroupSentinelEnv returns the "KEY=VALUE" environment entry that orchestrators append to a step/command subprocess's environment while that subprocess is inside, or is about to be inside, a CI log group.

func Register 

func Register(p provider.Provider)

Register registers a CI provider. Providers should call this in their init() function.

func RegisterPlugin 

func RegisterPlugin(p plugin.Plugin) error

RegisterPlugin registers a CI plugin for a component type. Plugins should call this in their init() function for self-registration.

func ReportSARIF added in v1.222.0 

func ReportSARIF(ctx context.Context, report SARIFReport) error

ReportSARIF publishes a SARIF document to the active CI provider's security-findings store when it implements the SARIFReporter capability (GitHub: Code Scanning / the Security tab). It is a no-op — returning nil — when no provider is detected or the detected provider is not a SARIFReporter.

func Reset added in v1.214.0 

func Reset()

Reset clears all registered providers. Intended for use in tests to ensure clean state between subtests that register providers.

func ResolveAdminCache added in v1.222.0 

func ResolveAdminCache() (cache.Backend, error)

ResolveAdminCache returns a cache backend for administering the cache (list and delete) without requiring an active CI runtime. Cache administration uses the provider's public API and a token, so it must work locally — outside a runner — which DetectCache deliberately does not allow.

It prefers the actively-detected provider (when running inside CI) and otherwise falls back to any registered cache-capable provider so a repo admin can manage the cache from their workstation. The resulting backend's save/restore may still be unavailable outside a runner; that is enforced by the backend itself (see the github backend's Save/Restore).

func ShouldPropagateLogGroupSentinel added in v1.223.0 

func ShouldPropagateLogGroupSentinel(atmosConfig *schema.AtmosConfiguration, dim Dimension) bool

ShouldPropagateLogGroupSentinel reports whether a subprocess launched at dim should inherit LogGroupSentinelEnv. It is true when a group is already open in this Atmos process, or when the configured mode/provider would open a group at dim. This keeps child Atmos invocations from suppressing their own grouping unless a parent group actually exists or will be opened for this boundary.

func StartLogGroup added in v1.223.0 

func StartLogGroup(title string) func()

StartLogGroup opens a provider-backed CI log group and returns a close function. It is a no-op when no provider is active or the provider has no log grouping capability. Grouping is best-effort: write failures are debug-only and must not change command success/failure behavior.

func SwapRegistryForTest added in v1.220.0 

func SwapRegistryForTest() func()

SwapRegistryForTest clears the provider registry and returns a restore function that puts the previous registry back in place when invoked. Intended for use in tests (including tests in other packages) that need to isolate themselves from the set of CI providers that are auto-registered via init() in the hosting binary — for example, tests asserting that ci.IsCI() returns false even when running under GitHub Actions.

func WriteStepSummary added in v1.222.0 

func WriteStepSummary(content string) error

WriteStepSummary appends content to the active CI provider's job step summary (e.g. GitHub Actions' $GITHUB_STEP_SUMMARY). It is a no-op — returning nil — when no CI provider is detected, or when the detected provider does not expose a summary destination (its OutputWriter resolves to a NoopOutputWriter or a FileOutputWriter with an empty summary path).

This is the seam used by non-CI subsystems (e.g. pkg/hooks scanner output) to surface markdown reports in the pipeline run without depending on the internal provider types or hard-coding any provider-specific env vars.

Types

type Annotation added in v1.222.0 

type Annotation = provider.Annotation

Annotation is a provider-neutral, line-anchored finding.

type AnnotationLevel added in v1.222.0 

type AnnotationLevel = provider.AnnotationLevel

AnnotationLevel is the severity bucket an Annotation renders as.

type BaseResolution added in v1.214.0 

type BaseResolution = provider.BaseResolution

BaseResolution contains the resolved base commit for affected detection.

type BranchStatus 

type BranchStatus = provider.BranchStatus

BranchStatus contains status information for a specific branch.

type CheckStatus 

type CheckStatus = provider.CheckStatus

CheckStatus contains status information for a single check.

type CheckStatusState 

type CheckStatusState = provider.CheckStatusState

CheckStatusState represents the simplified state for display.

type CloneRequest added in v1.223.0 

type CloneRequest struct {
	// Ref is the resolved ref/branch to be checked out (may be empty).
	Ref string

	// URI is the clone target URI (may be empty for named/no-arg clones whose
	// target is the CI repository itself).
	URI string
}

CloneRequest describes a requested git clone for fork-checkout trust evaluation. It carries only what the gate needs: the ref/branch that will be checked out and the clone target URI (used to detect cross-repository clones).

type Context added in v1.222.0 

type Context = provider.Context

Context is the public alias for CI run metadata supplied by a provider. Consumers outside pkg/ci (e.g. cmd/git for CI checkout replacement) use this alias; the underlying type lives in the internal provider package.

type DebugModeInfo added in v1.220.0 

type DebugModeInfo struct {
	// Active is true when the detected provider reports that CI debug
	// logging is enabled for the current run.
	Active bool

	// Provider is the name of the detected CI provider (e.g.
	// "github-actions"). Empty when no CI provider is detected.
	Provider string
}

DebugModeInfo describes the detected CI provider's debug-mode state. Returned by DetectDebugMode to keep callers provider-agnostic.

func DetectDebugMode added in v1.220.0 

func DetectDebugMode() DebugModeInfo

DetectDebugMode inspects the active CI provider for a debug-mode signal. Returns a zero-value DebugModeInfo when no provider is detected or the detected provider does not implement provider.DebugModeDetector.

Callers (e.g., the CLI startup path) use this to auto-promote their own log level when the user has opted into CI-side debug logging, without hard-coding any provider-specific environment variables.

type Dimension added in v1.223.0 

type Dimension int

Dimension identifies the boundary at which a caller wants to open a CI log group. Each dimension is emitted only under the grouping mode(s) that select it (see dimensionActive), which keeps the dimensions mutually exclusive. 

const (
	// DimensionStep is one group per workflow/custom-command step.
	DimensionStep Dimension = iota

	// DimensionPhase is one group per phase (init/plan/apply, …) of a single
	// component command invocation.
	DimensionPhase

	// DimensionInvocation is one group around a whole top-level `atmos` command.
	DimensionInvocation
)

type ExecuteOptions 

type ExecuteOptions struct {
	// Event is the hook event (e.g., "after.terraform.plan").
	Event string

	// AtmosConfig is the Atmos configuration.
	AtmosConfig *schema.AtmosConfiguration

	// Info contains component and stack information.
	Info *schema.ConfigAndStacksInfo

	// Output is the command output to process.
	Output string

	// ComponentType overrides the component type detection.
	// If empty, it's extracted from the event.
	ComponentType string

	// ForceCIMode forces CI mode even if environment detection fails.
	// This is set when --ci flag is used.
	ForceCIMode bool

	// CommandError is the error from the command execution, if any.
	// When set, check runs are updated with failure status.
	CommandError error

	// ExitCode is the exit code from the command execution. See HookContext.ExitCode
	// for semantics. Required for accurate success/failure reporting on commands
	// that fail before producing parseable terraform output (e.g., auth errors).
	ExitCode int

	// Aggregate carries command-specific aggregate result data for hook events
	// that summarize more than one component.
	Aggregate any
}

ExecuteOptions contains options for executing CI hooks.

type ForkVerdict added in v1.223.0 

type ForkVerdict struct {
	// Untrusted reports whether the requested clone would fetch untrusted fork
	// content under an elevated CI event and therefore requires an opt-in.
	Untrusted bool

	// Reason is a human-readable explanation of why the clone was flagged,
	// suitable for an error explanation. Empty when Untrusted is false.
	Reason string
}

ForkVerdict is the result of EvaluateForkCheckout.

func EvaluateForkCheckout added in v1.223.0 

func EvaluateForkCheckout(ciCtx *Context, req CloneRequest) ForkVerdict

EvaluateForkCheckout reports whether cloning req under the current CI event would fetch untrusted fork content. It is the provider-agnostic core of the fork-checkout safety gate that mirrors actions/checkout v7's refusal to fetch fork PR code in pull_request_target / workflow_run workflows.

A clone is flagged only when BOTH hold:

  1. the event is elevated (ciCtx.ElevatedEvent — set by the provider), and
  2. the request targets fork content: an explicit ref override that is a PR head/merge ref, or a clone URI whose owner/repo differs from the base CI repository.

The safe no-arg default (clone the base repository at its base ref) is never flagged. See docs/prd/native-ci/framework/fork-pr-trust-gate.md.

type PRInfo added in v1.222.0 

type PRInfo = provider.PRInfo

PRInfo is the public alias for pull request metadata.

type PRStatus 

type PRStatus = provider.PRStatus

PRStatus contains status information for a pull request.

type Provider 

type Provider = provider.Provider

Provider represents a CI/CD provider (GitHub Actions, GitLab CI, etc.).

type SARIFReport added in v1.222.0 

type SARIFReport = provider.SARIFReport

SARIFReport is a request to publish SARIF to the provider's findings store.

type Status 

type Status = provider.Status

Status represents the CI status for display (like gh pr status).

type StatusOptions 

type StatusOptions = provider.StatusOptions

StatusOptions contains options for fetching CI status.

Source Files

View all Source files

Directories

Path Synopsis
Package artifact is a generated GoMock package.
 Package artifact is a generated GoMock package.
github
local
s3
Package cache provides a CI-provider-scoped remote build cache, modeled on the artifact subsystem (pkg/ci/artifact).
 Package cache provides a CI-provider-scoped remote build cache, modeled on the artifact subsystem (pkg/ci/artifact).
github
Package github implements the CI cache Backend against the GitHub Actions cache (Cache Service v2).
 Package github implements the CI cache Backend against the GitHub Actions cache (Cache Service v2).
internal
plugin
Package plugin defines the CI plugin interface and related types for component type abstractions.
 Package plugin defines the CI plugin interface and related types for component type abstractions.
provider
Package provider defines the CI/CD provider interface and related types.
 Package provider defines the CI/CD provider interface and related types.
plugins
helm
Package helm provides the CI Plugin implementation for native Helm components.
 Package helm provides the CI Plugin implementation for native Helm components.
helmfile
Package helmfile provides the CI Plugin implementation for Helmfile components.
 Package helmfile provides the CI Plugin implementation for Helmfile components.
kubernetes
Package kubernetes provides CI job summaries for native Kubernetes components.
 Package kubernetes provides CI job summaries for native Kubernetes components.
terraform
Package terraform provides the CI provider implementation for Terraform.
 Package terraform provides the CI provider implementation for Terraform.
terraform/planfile
terraform/planfile/adapter
providers
generic
Package generic provides a fallback CI provider for when --ci flag is used but no specific CI platform is detected.
 Package generic provides a fallback CI provider for when --ci flag is used but no specific CI platform is detected.
github
Package github provides GitHub Actions CI provider implementation.
 Package github provides GitHub Actions CI provider implementation.
Package templates provides CI summary template loading and rendering.
 Package templates provides CI summary template loading and rendering.

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.