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

provider

package
v0.7.16 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: MPL-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package provider is the seam between the command line and the two analysis paths: one Provider implementation per git host (GitLab, GitHub) answers how to run the analysis, compute compliance, write the PBOM and perform the post-analysis actions, so the cmd package never branches on the provider name itself.

Package provider defines the Provider interface that every CI platform must implement, along with a global registry so the analyze command can dispatch to the right implementation without hard-coded if/switch chains.

Adding a new provider requires:

  1. Implement Provider in a new file (e.g. provider/bitbucket.go)
  2. Call Register(&BitbucketProvider{}) in an init() function
  3. Declare applicable controls in configuration/registry.go
  4. Add a Controls() implementation in control/catalog.go
  5. Add a ProviderConfig field in configuration/plumberconfig.go

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoRemote = errors.New("provider does not support remote analysis")

ErrNoRemote is returned by RunRemote when a provider only supports local analysis (e.g. GitLab, which always fetches via its own API).

Functions

func BuildControlStats 

func BuildControlStats(providerName, controlName string, result *control.AnalysisResult, pc *configuration.PlumberConfig, findings []opaengine.Finding) []control.StatLine

BuildControlStats invokes the registered StatsBuilder for providerName. Returns nil when no builder is registered.

func CapabilitiesOf added in v0.7.5 

func CapabilitiesOf(result *control.AnalysisResult, conf *configuration.Configuration) []capability.Match

CapabilitiesOf runs the capability recognizer over the analyzed pipeline: the one call both bills share (the --pbom artifact and the push's bom section), so the two documents never disagree about what the jobs do.

The list compiled is spec 4.2 and 4.6's: in platform mode, the declarations served on /context, compiled exactly as served (spec 3 decision 10), with no built-in fill-in, because the platform's own default IS the built-in list; removing a capability on the platform must remove it everywhere, including a served empty list, which recognizes nothing at all. A context without the field (an older platform, a failed /context fetch), or a served list that fails decoding or the bounds, means the built-in list alone (capability.Builtin). Standalone, it is capability.Effective: the .plumber.yaml key's declarations first, the built-in list filling in every name they do not declare. In both modes the file's key is ignored in platform mode, with one info line when it is set. A pattern that does not compile is skipped with one warning (Compile). Nil when the run produced no normalized pipeline.

Wrapper scripts are the one rule that reads the disk, and they are read only when the checkout IS the analyzed project (CheckoutIsAnalyzedProject) AND holds the analyzed ref (CheckoutIsAtRef): the same two gates the CI-file read and the config digest apply. GitRepoRoot is whatever repository the CLI stands in; with --project naming another one, a script of this checkout would otherwise become wrapper_script evidence for a project that never runs it, which is false coverage. Otherwise the root stays empty and the rule is off; the other five subjects need no checkout.

func GitHubPBOMDocument added in v0.7.16 

func GitHubPBOMDocument(result *control.AnalysisResult, conf *configuration.Configuration) *pbom.PBOM

GitHubPBOMDocument builds the GitHub bill of materials of a run: the container images, the actions and the reusable-workflow calls of the normalized workflow model, each enriched with the flags the run's findings assert. It is the one composition of the GitHub generator, shared by the --pbom artifacts (which stamp the score and the platform block on top) and the platform push's bom section, so the two can never disagree about what the pipeline uses. The findings are read from result as given: a platform-mode caller passes the policy runs' union. A nil conf reads as an empty configuration (github.com, no branch, controls on).

func Register 

func Register(p Provider)

Register adds p to the global registry. It is typically called from an init() function in the provider's implementation file. Panics if a provider with the same name is already registered.

func RegisterStatsBuilder 

func RegisterStatsBuilder(providerName string, b StatsBuilder)

RegisterStatsBuilder associates a StatsBuilder with a provider name. It is called from cmd/ init functions to avoid import cycles.

Types

type CIEnvMapping 

type CIEnvMapping struct {
	// ServerURL is the env var that holds the base URL of the forge server
	// (e.g. "CI_SERVER_URL" for GitLab, "GITHUB_SERVER_URL" for GitHub).
	ServerURL string
	// RepoPath is the env var that holds the project path (e.g.
	// "CI_PROJECT_PATH" / "GITHUB_REPOSITORY").
	RepoPath string
	// CommitSHA is the env var that holds the commit SHA (e.g.
	// "CI_COMMIT_SHA" / "GITHUB_SHA").
	CommitSHA string
	// RefName is the env var that holds the analyzed branch or tag name
	// (e.g. "CI_COMMIT_REF_NAME" / "GITHUB_REF_NAME"). It is the
	// authoritative ref in CI, preferred over the resolved default branch.
	RefName string
}

CIEnvMapping describes the CI environment variables a provider sets so the location linker can build stable source links anchored to the commit that triggered the analysis.

type GitHubProvider 

type GitHubProvider struct{}

GitHubProvider implements Provider for GitHub Actions.

func (*GitHubProvider) BlobURLInfix 

func (p *GitHubProvider) BlobURLInfix() string

func (*GitHubProvider) CIEnvVars 

func (p *GitHubProvider) CIEnvVars() CIEnvMapping

func (*GitHubProvider) ComputeCompliance 

func (p *GitHubProvider) ComputeCompliance(result *control.AnalysisResult, conf *configuration.Configuration) (float64, int)

func (*GitHubProvider) Controls 

func (p *GitHubProvider) Controls(pc *configuration.PlumberConfig) []control.ControlEntry

func (*GitHubProvider) Name 

func (p *GitHubProvider) Name() string

func (*GitHubProvider) PostAnalysisActions 

func (p *GitHubProvider) PostAnalysisActions(_ *cobra.Command, _ *control.AnalysisResult, _ *configuration.Configuration, _ PostActionSummary) error

func (*GitHubProvider) Run 

func (p *GitHubProvider) Run(conf *configuration.Configuration) (*control.AnalysisResult, error)

func (*GitHubProvider) RunRemote 

func (p *GitHubProvider) RunRemote(conf *configuration.Configuration) (*control.AnalysisResult, error)

func (*GitHubProvider) WritePBOM 

func (p *GitHubProvider) WritePBOM(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

func (*GitHubProvider) WritePBOMCycloneDX 

func (p *GitHubProvider) WritePBOMCycloneDX(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

type GitLabProvider 

type GitLabProvider struct{}

GitLabProvider implements Provider for GitLab CI/CD.

func (*GitLabProvider) BlobURLInfix 

func (p *GitLabProvider) BlobURLInfix() string

func (*GitLabProvider) CIEnvVars 

func (p *GitLabProvider) CIEnvVars() CIEnvMapping

func (*GitLabProvider) ComputeCompliance 

func (p *GitLabProvider) ComputeCompliance(result *control.AnalysisResult, conf *configuration.Configuration) (float64, int)

func (*GitLabProvider) Controls 

func (p *GitLabProvider) Controls(pc *configuration.PlumberConfig) []control.ControlEntry

func (*GitLabProvider) Name 

func (p *GitLabProvider) Name() string

func (*GitLabProvider) PostAnalysisActions 

func (p *GitLabProvider) PostAnalysisActions(cmd *cobra.Command, result *control.AnalysisResult, conf *configuration.Configuration, s PostActionSummary) error

func (*GitLabProvider) Run 

func (p *GitLabProvider) Run(conf *configuration.Configuration) (*control.AnalysisResult, error)

func (*GitLabProvider) RunRemote 

func (p *GitLabProvider) RunRemote(_ *configuration.Configuration) (*control.AnalysisResult, error)

func (*GitLabProvider) WritePBOM 

func (p *GitLabProvider) WritePBOM(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

func (*GitLabProvider) WritePBOMCycloneDX 

func (p *GitLabProvider) WritePBOMCycloneDX(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

type PlatformPolicyLine added in v0.4.60 

type PlatformPolicyLine = control.PlatformPolicyLine

PlatformPostSummary and PlatformPolicyLine are control's types, re-exported under this package's names because the post actions are named from here. They live in control/ because that is where the badge and the comment that render them live, and control cannot import provider.

type PlatformPostSummary added in v0.4.60 

type PlatformPostSummary = control.PlatformPostSummary

PlatformPostSummary and PlatformPolicyLine are control's types, re-exported under this package's names because the post actions are named from here. They live in control/ because that is where the badge and the comment that render them live, and control cannot import provider.

type PostActionSummary 

type PostActionSummary struct {
	Passed     bool
	GateLine   string
	Score      *control.PlumberScoreResult
	ScoreMode  bool
	ScorePoint bool
	Platform   *PlatformPostSummary
}

PostActionSummary bundles the gate outcome needed by PostAnalysisActions to avoid exceeding the parameter count limit. Passed is the active gate's verdict; GateLine is its human-readable rendering for the MR comment.

Platform is set only in platform mode (spec 2026-09-10-cli-platform-mode-policies-only s5) and is then what the badge and the merge-request comment report: Score is nil there by construction, because the run has no run-level grade and a locally computed one would be the figure that contradicts the platform's.

type Provider 

type Provider interface {
	// Name returns the canonical provider identifier ("gitlab", "github", …).
	Name() string

	// Controls returns the ordered catalog of controls for this provider.
	// The returned entries drive the compliance table and the per-control
	// rendering sections.
	Controls(pc *configuration.PlumberConfig) []control.ControlEntry

	// ComputeCompliance derives the overall compliance percentage and the
	// number of non-skipped controls that were evaluated from result.
	ComputeCompliance(result *control.AnalysisResult, conf *configuration.Configuration) (compliance float64, controlCount int)

	// Run executes the analysis for this provider using the local clone or
	// the provider's API, depending on conf.
	Run(conf *configuration.Configuration) (*control.AnalysisResult, error)

	// RunRemote fetches the pipeline from a remote API and runs analysis.
	// Returns ErrNoRemote when the provider does not support this mode.
	RunRemote(conf *configuration.Configuration) (*control.AnalysisResult, error)

	// WritePBOM writes a Pipeline Bill of Materials to filePath in the
	// provider's native PBOM format. platform is the platform-mode score
	// block (per-policy verdicts plus the platform's global score), nil on
	// every other run.
	WritePBOM(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

	// WritePBOMCycloneDX writes the PBOM in CycloneDX format.
	WritePBOMCycloneDX(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

	// PostAnalysisActions runs provider-specific post-analysis side-effects
	// such as posting MR comments or updating the project badge. Providers
	// that have no post-analysis actions return nil.
	PostAnalysisActions(cmd *cobra.Command, result *control.AnalysisResult, conf *configuration.Configuration, s PostActionSummary) error

	// BlobURLInfix returns the URL segment between the repository base URL
	// and the file path when building clickable source links.
	// Example: GitLab "/-/blob/", GitHub "/blob/".
	BlobURLInfix() string

	// CIEnvVars returns the mapping of CI environment variables used to
	// build stable source links when running inside a CI pipeline.
	CIEnvVars() CIEnvMapping
}

Provider is the contract every CI platform must satisfy. The analyze command resolves the active provider via Get() and delegates all provider-specific logic through this interface, keeping the shared pipeline (compliance calculation, output rendering, artifact writing) provider-agnostic.

func Get 

func Get(name string) (Provider, bool)

Get returns the provider registered under name and whether it was found.

type StatsBuilder 

type StatsBuilder func(controlName string, result *control.AnalysisResult, pc *configuration.PlumberConfig, findings []opaengine.Finding) []control.StatLine

StatsBuilder computes the stat lines displayed above the findings block for a single control. It is registered separately from the Provider interface because the implementation often depends on cmd-internal helpers that would create import cycles if embedded in the interface. cmd/ registers the builder via RegisterStatsBuilder during init.

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.