gitenv

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: GPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package gitenv provides auto-detection and abstraction for CI/CD environments. It detects GitHub Actions, GitLab CI, and other CI systems from environment variables and provides a unified interface for accessing repository and commit information.

Index

Constants

View Source 
const (
	ProviderGitHub    = "github"
	ProviderGitLab    = "gitlab"
	ProviderBitbucket = "bitbucket"
	ProviderManual    = "manual"
)
View Source 
const SummaryMarker = "<!-- openctem-summary -->"

SummaryMarker tags the single sticky PR/MR summary comment so it is updated in place each run instead of re-posted.

Variables

This section is empty.

Functions

func ExtractMarkers added in v0.4.0 

func ExtractMarkers(bodies []string) map[string]bool

ExtractMarkers returns the set of finding keys already present in the given comment bodies (parsed from the hidden markers).

func MarkerComment added in v0.4.0 

func MarkerComment(key string) string

MarkerComment returns the hidden marker to append to a comment body for the given finding key.

Types

type GitEnv 

type GitEnv interface {
	// Provider returns the provider name (github, gitlab, bitbucket, etc.)
	Provider() string

	// IsActive returns true if this CI environment is detected
	IsActive() bool

	// Repository info
	ProjectID() string
	ProjectName() string
	ProjectURL() string
	BlobURL() string

	// CanonicalRepoName returns the full canonical repository name including the provider domain.
	// Format: {domain}/{owner}/{repo}
	// Examples:
	//   - github.com/openctemio/api
	//   - gitlab.com/myorg/myrepo
	// This ensures unique asset identification across different Git providers.
	CanonicalRepoName() string

	// Commit info
	CommitSha() string
	CommitBranch() string
	CommitTitle() string
	CommitTag() string
	DefaultBranch() string

	// MR/PR info
	MergeRequestID() string
	MergeRequestTitle() string
	SourceBranch() string
	TargetBranch() string
	TargetBranchSha() string

	// CI info
	JobURL() string

	// Actions
	CreateMRComment(option MRCommentOption) error

	// ExistingFindingMarkers returns the set of finding keys already commented on
	// the current PR/MR (parsed from hidden markers), so a re-run can skip them.
	// Returns an empty map when not in a PR/MR or when listing is unsupported.
	ExistingFindingMarkers() (map[string]bool, error)

	// UpsertSummaryComment posts (or updates in place) the single sticky security
	// summary comment on the current PR/MR. The body should NOT include the
	// marker — the implementation appends SummaryMarker. No-op outside a PR/MR.
	UpsertSummaryComment(body string) error
}

GitEnv provides a unified interface for CI/CD environment information. Implementations detect and read from CI-specific environment variables.

func Detect 

func Detect() GitEnv

Detect auto-detects the CI environment and returns the appropriate GitEnv. Returns nil if no CI environment is detected.

func DetectFromDirectory 

func DetectFromDirectory(dir string, verbose bool) GitEnv

DetectFromDirectory detects git information from a local directory. Useful when running locally without CI environment.

func DetectWithVerbose 

func DetectWithVerbose(verbose bool) GitEnv

DetectWithVerbose auto-detects the CI environment with optional verbose logging.

type GitHubEnv 

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

GitHubEnv provides GitHub Actions CI environment information.

func NewGitHub 

func NewGitHub() (*GitHubEnv, error)

NewGitHub creates a new GitHub Actions environment.

func (*GitHubEnv) BlobURL 

func (g *GitHubEnv) BlobURL() string

BlobURL returns the URL for viewing files.

func (*GitHubEnv) CanonicalRepoName 

func (g *GitHubEnv) CanonicalRepoName() string

CanonicalRepoName returns the full canonical repository name including domain. Format: github.com/{owner}/{repo} (or custom domain for GitHub Enterprise) This ensures unique asset identification across different Git providers.

func (*GitHubEnv) CommitBranch 

func (g *GitHubEnv) CommitBranch() string

CommitBranch returns the current branch name.

func (*GitHubEnv) CommitSha 

func (g *GitHubEnv) CommitSha() string

CommitSha returns the current commit SHA.

func (*GitHubEnv) CommitTag 

func (g *GitHubEnv) CommitTag() string

CommitTag returns the tag name if this is a tag push.

func (*GitHubEnv) CommitTitle 

func (g *GitHubEnv) CommitTitle() string

CommitTitle returns the commit message.

func (*GitHubEnv) CreateMRComment 

func (g *GitHubEnv) CreateMRComment(option MRCommentOption) error

CreateMRComment creates a review comment on a pull request.

func (*GitHubEnv) DefaultBranch 

func (g *GitHubEnv) DefaultBranch() string

DefaultBranch returns the default branch name.

func (*GitHubEnv) ExistingFindingMarkers added in v0.4.0 

func (g *GitHubEnv) ExistingFindingMarkers() (map[string]bool, error)

ExistingFindingMarkers lists the PR's review comments and extracts the finding markers already posted, so a re-run can skip them (idempotency). Best-effort: any error returns an empty set so commenting degrades to "may duplicate" rather than failing the scan.

func (*GitHubEnv) IsActive 

func (g *GitHubEnv) IsActive() bool

IsActive returns true if running in GitHub Actions.

func (*GitHubEnv) JobURL 

func (g *GitHubEnv) JobURL() string

JobURL returns the URL for the current job.

func (*GitHubEnv) MergeRequestID 

func (g *GitHubEnv) MergeRequestID() string

MergeRequestID returns the PR number.

func (*GitHubEnv) MergeRequestTitle 

func (g *GitHubEnv) MergeRequestTitle() string

MergeRequestTitle returns the PR title.

func (*GitHubEnv) ProjectID 

func (g *GitHubEnv) ProjectID() string

ProjectID returns the GitHub repository ID.

func (*GitHubEnv) ProjectName 

func (g *GitHubEnv) ProjectName() string

ProjectName returns owner/repo format.

func (*GitHubEnv) ProjectURL 

func (g *GitHubEnv) ProjectURL() string

ProjectURL returns the repository URL.

func (*GitHubEnv) Provider 

func (g *GitHubEnv) Provider() string

Provider returns "github".

func (*GitHubEnv) SetVerbose 

func (g *GitHubEnv) SetVerbose(v bool)

SetVerbose enables verbose logging.

func (*GitHubEnv) SourceBranch 

func (g *GitHubEnv) SourceBranch() string

SourceBranch returns the source branch for PRs.

func (*GitHubEnv) TargetBranch 

func (g *GitHubEnv) TargetBranch() string

TargetBranch returns the target branch for PRs.

func (*GitHubEnv) TargetBranchSha 

func (g *GitHubEnv) TargetBranchSha() string

TargetBranchSha returns the base commit SHA for PRs.

func (*GitHubEnv) UpsertSummaryComment added in v0.4.0 

func (g *GitHubEnv) UpsertSummaryComment(body string) error

UpsertSummaryComment posts or updates the single sticky security summary comment on the PR (a PR-level issue comment, not an inline review comment).

type GitLabEnv 

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

GitLabEnv provides GitLab CI environment information.

func NewGitLab 

func NewGitLab() (*GitLabEnv, error)

NewGitLab creates a new GitLab CI environment.

func (*GitLabEnv) BlobURL 

func (g *GitLabEnv) BlobURL() string

BlobURL returns the URL for viewing files.

func (*GitLabEnv) CanonicalRepoName 

func (g *GitLabEnv) CanonicalRepoName() string

CanonicalRepoName returns the full canonical repository name including domain. Format: {domain}/{namespace}/{project} Examples:

  • gitlab.com/myorg/myrepo
  • gitlab.mycompany.com/team/project

This ensures unique asset identification across different Git providers.

func (*GitLabEnv) CommitBranch 

func (g *GitLabEnv) CommitBranch() string

CommitBranch returns the current branch name.

func (*GitLabEnv) CommitSha 

func (g *GitLabEnv) CommitSha() string

CommitSha returns the current commit SHA.

func (*GitLabEnv) CommitTag 

func (g *GitLabEnv) CommitTag() string

CommitTag returns the tag name if this is a tag pipeline.

func (*GitLabEnv) CommitTitle 

func (g *GitLabEnv) CommitTitle() string

CommitTitle returns the commit message.

func (*GitLabEnv) CreateMRComment 

func (g *GitLabEnv) CreateMRComment(option MRCommentOption) error

CreateMRComment creates a discussion on a merge request.

func (*GitLabEnv) DefaultBranch 

func (g *GitLabEnv) DefaultBranch() string

DefaultBranch returns the default branch name.

func (*GitLabEnv) ExistingFindingMarkers added in v0.4.0 

func (g *GitLabEnv) ExistingFindingMarkers() (map[string]bool, error)

ExistingFindingMarkers lists the MR's discussion notes and extracts the finding markers already posted, so a re-run can skip them (idempotency). Best-effort: errors return an empty set rather than failing the scan.

func (*GitLabEnv) IsActive 

func (g *GitLabEnv) IsActive() bool

IsActive returns true if running in GitLab CI.

func (*GitLabEnv) JobURL 

func (g *GitLabEnv) JobURL() string

JobURL returns the URL for the current job.

func (*GitLabEnv) MergeRequestID 

func (g *GitLabEnv) MergeRequestID() string

MergeRequestID returns the MR IID.

func (*GitLabEnv) MergeRequestTitle 

func (g *GitLabEnv) MergeRequestTitle() string

MergeRequestTitle returns the MR title.

func (*GitLabEnv) ProjectID 

func (g *GitLabEnv) ProjectID() string

ProjectID returns the GitLab project ID.

func (*GitLabEnv) ProjectName 

func (g *GitLabEnv) ProjectName() string

ProjectName returns the project name.

func (*GitLabEnv) ProjectURL 

func (g *GitLabEnv) ProjectURL() string

ProjectURL returns the project URL.

func (*GitLabEnv) Provider 

func (g *GitLabEnv) Provider() string

Provider returns "gitlab".

func (*GitLabEnv) SetVerbose 

func (g *GitLabEnv) SetVerbose(v bool)

SetVerbose enables verbose logging.

func (*GitLabEnv) SourceBranch 

func (g *GitLabEnv) SourceBranch() string

SourceBranch returns the source branch for MRs.

func (*GitLabEnv) TargetBranch 

func (g *GitLabEnv) TargetBranch() string

TargetBranch returns the target branch for MRs.

func (*GitLabEnv) TargetBranchSha 

func (g *GitLabEnv) TargetBranchSha() string

TargetBranchSha returns the base commit SHA for MRs.

func (*GitLabEnv) UpsertSummaryComment added in v0.4.0 

func (g *GitLabEnv) UpsertSummaryComment(body string) error

UpsertSummaryComment posts or updates the single sticky security summary note on the MR.

type MRCommentOption 

type MRCommentOption struct {
	Title     string
	Body      string
	Path      string
	StartLine int
	EndLine   int
}

MRCommentOption configures a merge request / pull request comment.

type ManualEnv 

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

ManualEnv is a manual/local environment when no CI is detected.

func NewManualEnv 

func NewManualEnv(repoURL, branch, commitSha string) *ManualEnv

NewManualEnv creates a manual environment with optional override values.

func (*ManualEnv) BlobURL 

func (m *ManualEnv) BlobURL() string

func (*ManualEnv) CanonicalRepoName 

func (m *ManualEnv) CanonicalRepoName() string

CanonicalRepoName returns the repo URL as-is for manual environments.

func (*ManualEnv) CommitBranch 

func (m *ManualEnv) CommitBranch() string

func (*ManualEnv) CommitSha 

func (m *ManualEnv) CommitSha() string

func (*ManualEnv) CommitTag 

func (m *ManualEnv) CommitTag() string

func (*ManualEnv) CommitTitle 

func (m *ManualEnv) CommitTitle() string

func (*ManualEnv) CreateMRComment 

func (m *ManualEnv) CreateMRComment(_ MRCommentOption) error

func (*ManualEnv) DefaultBranch 

func (m *ManualEnv) DefaultBranch() string

func (*ManualEnv) ExistingFindingMarkers added in v0.4.0 

func (m *ManualEnv) ExistingFindingMarkers() (map[string]bool, error)

ExistingFindingMarkers returns an empty set — a manual/local env has no PR/MR.

func (*ManualEnv) IsActive 

func (m *ManualEnv) IsActive() bool

func (*ManualEnv) JobURL 

func (m *ManualEnv) JobURL() string

func (*ManualEnv) MergeRequestID 

func (m *ManualEnv) MergeRequestID() string

func (*ManualEnv) MergeRequestTitle 

func (m *ManualEnv) MergeRequestTitle() string

func (*ManualEnv) ProjectID 

func (m *ManualEnv) ProjectID() string

func (*ManualEnv) ProjectName 

func (m *ManualEnv) ProjectName() string

func (*ManualEnv) ProjectURL 

func (m *ManualEnv) ProjectURL() string

func (*ManualEnv) Provider 

func (m *ManualEnv) Provider() string

func (*ManualEnv) SourceBranch 

func (m *ManualEnv) SourceBranch() string

func (*ManualEnv) TargetBranch 

func (m *ManualEnv) TargetBranch() string

func (*ManualEnv) TargetBranchSha 

func (m *ManualEnv) TargetBranchSha() string

func (*ManualEnv) UpsertSummaryComment added in v0.4.0 

func (m *ManualEnv) UpsertSummaryComment(_ string) error

UpsertSummaryComment is a no-op for a manual/local env (no PR/MR).

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.