gitlabci

package
v0.7.4 Latest Latest
Warning

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

 Go to latest Published: Mar 27, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package gitlabci provides GitLab API client for MR integration

Package gitlabci provides GitLab CI pipeline generation

Index

Constants

View Source 
const (
	// DefaultStagesPrefix is the default prefix for stage names
	DefaultStagesPrefix = "deploy"
	// WhenManual is the GitLab CI "when: manual" value for jobs that require manual trigger
	WhenManual = "manual"
)

Variables

This section is empty.

Functions

func FindTerraCIComment 

func FindTerraCIComment(notes []*gitlab.Note) *gitlab.Note

FindTerraCIComment finds an existing terraci comment in the GitLab notes

Types

type ArtifactReports 

type ArtifactReports struct {
	// Terraform report paths
	Terraform []string `yaml:"terraform,omitempty" json:"terraform,omitempty" jsonschema:"description=Terraform report paths"`
	// JUnit report paths
	JUnit []string `yaml:"junit,omitempty" json:"junit,omitempty" jsonschema:"description=JUnit report paths"`
	// Cobertura coverage report paths
	Cobertura []string `yaml:"cobertura,omitempty" json:"cobertura,omitempty" jsonschema:"description=Cobertura coverage report paths"`
}

ArtifactReports defines artifact reports configuration

type Artifacts 

type Artifacts struct {
	Paths     []string `yaml:"paths,omitempty"`
	ExpireIn  string   `yaml:"expire_in,omitempty"`
	Reports   *Reports `yaml:"reports,omitempty"`
	Name      string   `yaml:"name,omitempty"`
	Untracked bool     `yaml:"untracked,omitempty"`
	When      string   `yaml:"when,omitempty"`
	ExposeAs  string   `yaml:"expose_as,omitempty"`
}

Artifacts represents job artifacts

type ArtifactsConfig 

type ArtifactsConfig struct {
	// Paths is a list of file/directory paths to include as artifacts
	Paths []string `yaml:"paths,omitempty" json:"paths,omitempty" jsonschema:"description=File/directory paths to include as artifacts"`
	// ExpireIn specifies how long artifacts should be kept (e.g., "1 day", "1 week")
	ExpireIn string `` /* 132-byte string literal not displayed */
	// Reports defines artifact reports (e.g., terraform)
	Reports *ArtifactReports `yaml:"reports,omitempty" json:"reports,omitempty" jsonschema:"description=Artifact reports configuration"`
	// Name is the artifact archive name
	Name string `yaml:"name,omitempty" json:"name,omitempty" jsonschema:"description=Artifact archive name"`
	// Untracked includes all untracked files
	Untracked bool `yaml:"untracked,omitempty" json:"untracked,omitempty" jsonschema:"description=Include all untracked files"`
	// When specifies when to upload artifacts: on_success, on_failure, always
	When string `` /* 137-byte string literal not displayed */
	// ExposeAs makes artifacts available in MR UI
	ExposeAs string `yaml:"expose_as,omitempty" json:"expose_as,omitempty" jsonschema:"description=Makes artifacts available in MR UI"`
}

ArtifactsConfig defines GitLab CI artifacts configuration

type Cache 

type Cache struct {
	Key    string   `yaml:"key"`
	Paths  []string `yaml:"paths"`
	Policy string   `yaml:"policy,omitempty"` // pull, push, pull-push
}

Cache represents GitLab CI cache configuration

type CfgSecret 

type CfgSecret struct {
	// Vault configures HashiCorp Vault secret (can be string shorthand or object)
	Vault *CfgVaultSecret `yaml:"vault,omitempty" json:"vault,omitempty" jsonschema:"description=HashiCorp Vault secret configuration"`
	// File indicates if secret should be written to a file
	File bool `yaml:"file,omitempty" json:"file,omitempty" jsonschema:"description=Write secret to a file"`
}

CfgSecret defines a CI/CD secret in the config file (from an external secret manager). This is the config-input type; the pipeline-output type is Secret in types.go.

type CfgVaultSecret 

type CfgVaultSecret struct {
	// Engine is the secrets engine (e.g., "kv-v2") - for full syntax
	Engine *VaultEngine `yaml:"engine,omitempty" json:"engine,omitempty" jsonschema:"description=Vault secrets engine configuration"`
	// Path is the path to the secret in Vault - for full syntax
	Path string `yaml:"path,omitempty" json:"path,omitempty" jsonschema:"description=Path to the secret in Vault"`
	// Field is the field to extract from the secret - for full syntax
	Field string `yaml:"field,omitempty" json:"field,omitempty" jsonschema:"description=Field to extract from the secret"`
	// Shorthand is the string shorthand format (path/to/secret/field@namespace)
	Shorthand string `yaml:"-" jsonschema:"-"`
}

CfgVaultSecret defines a secret from HashiCorp Vault in the config file. Supports both full object syntax and string shorthand (path/to/secret/field@namespace).

func (*CfgVaultSecret) UnmarshalYAML 

func (v *CfgVaultSecret) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling for CfgVaultSecret to support string shorthand

type Client 

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

Client wraps the official GitLab client

func NewClient 

func NewClient(baseURL, token string) *Client

NewClient creates a new GitLab API client

func NewClientFromEnv 

func NewClientFromEnv() *Client

NewClientFromEnv creates a client from GitLab CI environment variables

func (*Client) AddMRLabels 

func (c *Client) AddMRLabels(projectID string, mrIID int64, labels []string) error

AddMRLabels adds labels to an MR

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the GitLab instance base URL

func (*Client) CreateMRNote 

func (c *Client) CreateMRNote(projectID string, mrIID int64, body string) (*gitlab.Note, error)

CreateMRNote creates a new note on an MR

func (*Client) GetMRNotes 

func (c *Client) GetMRNotes(projectID string, mrIID int64) ([]*gitlab.Note, error)

GetMRNotes retrieves all notes for an MR

func (*Client) HasToken 

func (c *Client) HasToken() bool

HasToken returns true if a token is configured

func (*Client) UpdateMRNote 

func (c *Client) UpdateMRNote(projectID string, mrIID, noteID int64, body string) (*gitlab.Note, error)

UpdateMRNote updates an existing note on an MR

type Config 

type Config struct {
	// TerraformBinary is the terraform binary to use (e.g., "terraform", "tofu")
	TerraformBinary string `` /* 148-byte string literal not displayed */
	// Image is the Docker image for terraform jobs (in default section)
	// Supports both string format ("hashicorp/terraform:1.6") and object format with entrypoint
	Image Image `yaml:"image" json:"image" jsonschema:"description=Docker image for terraform jobs,default=hashicorp/terraform:1.6"`
	// StagesPrefix is the prefix for stage names (e.g., "deploy" -> "deploy-0", "deploy-1")
	StagesPrefix string `` /* 160-byte string literal not displayed */
	// Parallelism limits concurrent jobs per stage
	Parallelism int `yaml:"parallelism" json:"parallelism" jsonschema:"description=Maximum parallel jobs per stage,minimum=1,default=5"`
	// Variables to set in the pipeline (global variables section)
	Variables map[string]string `yaml:"variables,omitempty" json:"variables,omitempty" jsonschema:"description=Global pipeline variables"`
	// PlanEnabled enables terraform plan stage
	PlanEnabled bool `yaml:"plan_enabled" json:"plan_enabled" jsonschema:"description=Enable terraform plan stage,default=true"`
	// PlanOnly generates only plan jobs without apply jobs
	PlanOnly bool `yaml:"plan_only" json:"plan_only" jsonschema:"description=Generate only plan jobs (no apply jobs),default=false"`
	// AutoApprove skips manual approval for apply
	AutoApprove bool `` /* 126-byte string literal not displayed */
	// CacheEnabled enables caching of .terraform directory
	CacheEnabled bool `yaml:"cache_enabled" json:"cache_enabled" jsonschema:"description=Enable caching of .terraform directory,default=true"`
	// InitEnabled automatically runs terraform init after cd to module directory
	InitEnabled bool `` /* 139-byte string literal not displayed */
	// Rules defines workflow-level rules for conditional pipeline execution
	Rules []Rule `yaml:"rules,omitempty" json:"rules,omitempty" jsonschema:"description=Workflow rules for conditional pipeline execution"`
	// JobDefaults defines default settings for all jobs (applied before overwrites)
	JobDefaults *JobDefaults `yaml:"job_defaults,omitempty" json:"job_defaults,omitempty" jsonschema:"description=Default settings applied to all jobs"`
	// Overwrites defines job-level overrides for plan and apply jobs
	Overwrites []JobOverwrite `yaml:"overwrites,omitempty" json:"overwrites,omitempty" jsonschema:"description=Job-level overrides for plan or apply jobs"`
	// MR contains merge request integration settings
	MR *MRConfig `yaml:"mr,omitempty" json:"mr,omitempty" jsonschema:"description=Merge request integration settings"`
}

Config contains GitLab CI specific settings

func (*Config) GetImage 

func (g *Config) GetImage() Image

GetImage returns the configured image

type DefaultConfig 

type DefaultConfig struct {
	Image *ImageConfig `yaml:"image,omitempty"`
}

DefaultConfig represents default job configuration (only image in default section)

type Generator 

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

Generator generates GitLab CI pipelines

func NewGenerator 

func NewGenerator(cfg *Config, contributions []*pipeline.Contribution, depGraph *graph.DependencyGraph, modules []*discovery.Module) *Generator

NewGenerator creates a new pipeline generator

func (*Generator) DryRun 

func (g *Generator) DryRun(targetModules []*discovery.Module) (*pipeline.DryRunResult, error)

DryRun returns information about what would be generated without creating YAML

func (*Generator) Generate 

func (g *Generator) Generate(targetModules []*discovery.Module) (pipeline.GeneratedPipeline, error)

Generate creates a GitLab CI pipeline for the given modules

type IDToken 

type IDToken struct {
	Aud string `yaml:"aud"`
}

IDToken represents GitLab CI OIDC token configuration

type Image 

type Image struct {
	// Name is the image name (e.g., "hashicorp/terraform:1.6")
	Name string `yaml:"name,omitempty" json:"name,omitempty" jsonschema:"description=Docker image name"`
	// Entrypoint overrides the default entrypoint
	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty" jsonschema:"description=Override default entrypoint"`
}

Image defines a Docker image configuration Supports both string format and object format with entrypoint

func (*Image) HasEntrypoint 

func (img *Image) HasEntrypoint() bool

HasEntrypoint returns true if entrypoint is configured

func (*Image) String 

func (img *Image) String() string

String returns the image name

func (*Image) UnmarshalYAML 

func (img *Image) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling for Image to support string shorthand

type ImageConfig 

type ImageConfig struct {
	Name       string   `yaml:"name,omitempty"`
	Entrypoint []string `yaml:"entrypoint,omitempty"`
}

ImageConfig represents GitLab CI image configuration Can be marshaled as either string or object with entrypoint

func (ImageConfig) MarshalYAML 

func (img ImageConfig) MarshalYAML() (any, error)

MarshalYAML implements custom marshaling to output string when no entrypoint

type Job 

type Job struct {
	Stage         string              `yaml:"stage"`
	Image         *ImageConfig        `yaml:"image,omitempty"`
	Script        []string            `yaml:"script"`
	BeforeScript  []string            `yaml:"before_script,omitempty"`
	AfterScript   []string            `yaml:"after_script,omitempty"`
	Variables     map[string]string   `yaml:"variables,omitempty"`
	Needs         []JobNeed           `yaml:"needs,omitempty"`
	Rules         []Rule              `yaml:"rules,omitempty"`
	Artifacts     *Artifacts          `yaml:"artifacts,omitempty"`
	Cache         *Cache              `yaml:"cache,omitempty"`
	Secrets       map[string]*Secret  `yaml:"secrets,omitempty"`
	IDTokens      map[string]*IDToken `yaml:"id_tokens,omitempty"`
	When          string              `yaml:"when,omitempty"`
	AllowFailure  bool                `yaml:"allow_failure,omitempty"`
	Tags          []string            `yaml:"tags,omitempty"`
	ResourceGroup string              `yaml:"resource_group,omitempty"`
}

Job represents a GitLab CI job

type JobConfig 

type JobConfig interface {
	GetImage() *Image
	GetIDTokens() map[string]IDToken
	GetSecrets() map[string]CfgSecret
	GetBeforeScript() []string
	GetAfterScript() []string
	GetArtifacts() *ArtifactsConfig
	GetTags() []string
	GetRules() []Rule
	GetVariables() map[string]string
}

JobConfig is an interface for job configuration (defaults and overwrites)

type JobDefaults 

type JobDefaults struct {
	// Image overrides the Docker image for all jobs
	Image *Image `yaml:"image,omitempty" json:"image,omitempty" jsonschema:"description=Docker image override for all jobs"`
	// IDTokens sets OIDC tokens for all jobs
	IDTokens map[string]IDToken `yaml:"id_tokens,omitempty" json:"id_tokens,omitempty" jsonschema:"description=OIDC tokens for cloud provider authentication"`
	// Secrets sets secrets for all jobs
	Secrets map[string]CfgSecret `yaml:"secrets,omitempty" json:"secrets,omitempty" jsonschema:"description=Secrets from external secret managers"`
	// BeforeScript sets before_script for all jobs
	BeforeScript []string `yaml:"before_script,omitempty" json:"before_script,omitempty" jsonschema:"description=Commands to run before each job"`
	// AfterScript sets after_script for all jobs
	AfterScript []string `yaml:"after_script,omitempty" json:"after_script,omitempty" jsonschema:"description=Commands to run after each job"`
	// Artifacts sets artifacts configuration for all jobs
	Artifacts *ArtifactsConfig `yaml:"artifacts,omitempty" json:"artifacts,omitempty" jsonschema:"description=GitLab CI artifacts configuration"`
	// Tags sets runner tags for all jobs
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" jsonschema:"description=GitLab runner tags"`
	// Rules sets job-level rules for all jobs
	Rules []Rule `yaml:"rules,omitempty" json:"rules,omitempty" jsonschema:"description=Job-level rules"`
	// Variables sets additional variables for all jobs
	Variables map[string]string `yaml:"variables,omitempty" json:"variables,omitempty" jsonschema:"description=Additional variables"`
}

JobDefaults defines default settings for all generated jobs

func (*JobDefaults) GetAfterScript 

func (j *JobDefaults) GetAfterScript() []string

func (*JobDefaults) GetArtifacts 

func (j *JobDefaults) GetArtifacts() *ArtifactsConfig

func (*JobDefaults) GetBeforeScript 

func (j *JobDefaults) GetBeforeScript() []string

func (*JobDefaults) GetIDTokens 

func (j *JobDefaults) GetIDTokens() map[string]IDToken

func (*JobDefaults) GetImage 

func (j *JobDefaults) GetImage() *Image

JobDefaults implements JobConfig

func (*JobDefaults) GetRules 

func (j *JobDefaults) GetRules() []Rule

func (*JobDefaults) GetSecrets 

func (j *JobDefaults) GetSecrets() map[string]CfgSecret

func (*JobDefaults) GetTags 

func (j *JobDefaults) GetTags() []string

func (*JobDefaults) GetVariables 

func (j *JobDefaults) GetVariables() map[string]string

type JobNeed 

type JobNeed struct {
	Job      string `yaml:"job"`
	Optional bool   `yaml:"optional,omitempty"`
}

JobNeed represents a job dependency

type JobOverwrite 

type JobOverwrite struct {
	// Type specifies which jobs to override: "plan" or "apply"
	Type JobOverwriteType `yaml:"type" json:"type" jsonschema:"description=Type of jobs to override,enum=plan,enum=apply,required"`
	// Image overrides the Docker image for matching jobs
	Image *Image `yaml:"image,omitempty" json:"image,omitempty" jsonschema:"description=Docker image override for matching jobs"`
	// IDTokens overrides OIDC tokens for matching jobs
	IDTokens map[string]IDToken `yaml:"id_tokens,omitempty" json:"id_tokens,omitempty" jsonschema:"description=OIDC tokens for matching jobs"`
	// Secrets overrides secrets for matching jobs
	Secrets map[string]CfgSecret `yaml:"secrets,omitempty" json:"secrets,omitempty" jsonschema:"description=Secrets for matching jobs"`
	// BeforeScript overrides before_script for matching jobs
	BeforeScript []string `yaml:"before_script,omitempty" json:"before_script,omitempty" jsonschema:"description=Commands to run before matching jobs"`
	// AfterScript overrides after_script for matching jobs
	AfterScript []string `yaml:"after_script,omitempty" json:"after_script,omitempty" jsonschema:"description=Commands to run after matching jobs"`
	// Artifacts overrides artifacts configuration for matching jobs
	Artifacts *ArtifactsConfig `yaml:"artifacts,omitempty" json:"artifacts,omitempty" jsonschema:"description=Artifacts configuration for matching jobs"`
	// Tags overrides runner tags for matching jobs
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" jsonschema:"description=Runner tags for matching jobs"`
	// Rules sets job-level rules for matching jobs
	Rules []Rule `yaml:"rules,omitempty" json:"rules,omitempty" jsonschema:"description=Job-level rules for matching jobs"`
	// Variables overrides variables for matching jobs
	Variables map[string]string `yaml:"variables,omitempty" json:"variables,omitempty" jsonschema:"description=Variables for matching jobs"`
}

JobOverwrite defines job-level overrides for plan or apply jobs

func (*JobOverwrite) GetAfterScript 

func (j *JobOverwrite) GetAfterScript() []string

func (*JobOverwrite) GetArtifacts 

func (j *JobOverwrite) GetArtifacts() *ArtifactsConfig

func (*JobOverwrite) GetBeforeScript 

func (j *JobOverwrite) GetBeforeScript() []string

func (*JobOverwrite) GetIDTokens 

func (j *JobOverwrite) GetIDTokens() map[string]IDToken

func (*JobOverwrite) GetImage 

func (j *JobOverwrite) GetImage() *Image

JobOverwrite implements JobConfig

func (*JobOverwrite) GetRules 

func (j *JobOverwrite) GetRules() []Rule

func (*JobOverwrite) GetSecrets 

func (j *JobOverwrite) GetSecrets() map[string]CfgSecret

func (*JobOverwrite) GetTags 

func (j *JobOverwrite) GetTags() []string

func (*JobOverwrite) GetVariables 

func (j *JobOverwrite) GetVariables() map[string]string

type JobOverwriteType 

type JobOverwriteType string

JobOverwriteType defines the type of jobs to override 

const (
	// OverwriteTypePlan applies to plan jobs only
	OverwriteTypePlan JobOverwriteType = "plan"
	// OverwriteTypeApply applies to apply jobs only
	OverwriteTypeApply JobOverwriteType = "apply"
)

type MRCommentConfig 

type MRCommentConfig struct {
	// Enabled enables MR comments (default: true when in MR pipeline)
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty" jsonschema:"description=Enable MR comments,default=true"`
	// OnChangesOnly only comment when there are changes (default: false)
	OnChangesOnly bool `` /* 126-byte string literal not displayed */
	// IncludeDetails includes full plan output in collapsible sections
	IncludeDetails bool `` /* 151-byte string literal not displayed */
}

MRCommentConfig contains settings for MR/PR comments. Shared by both GitLab and GitHub plugins.

type MRConfig 

type MRConfig struct {
	// Comment enables MR comment with plan summary (auto-detected in MR pipelines)
	Comment *MRCommentConfig `yaml:"comment,omitempty" json:"comment,omitempty" jsonschema:"description=MR comment configuration"`
	// Labels to add to MR, supports placeholders: {service}, {environment}, {region}, {module}
	Labels []string `` /* 168-byte string literal not displayed */
	// SummaryJob configures the summary job that posts MR comments
	SummaryJob *SummaryJobConfig `yaml:"summary_job,omitempty" json:"summary_job,omitempty" jsonschema:"description=Summary job configuration"`
}

MRConfig contains settings for MR integration

type MRContext 

type MRContext struct {
	ProjectID    string
	ProjectPath  string
	MRIID        int64
	SourceBranch string
	TargetBranch string
	PipelineID   string
	JobID        string
	CommitSHA    string
	InMR         bool
}

MRContext contains information about the current MR context

func DetectMRContext 

func DetectMRContext() *MRContext

DetectMRContext detects if we're running in a GitLab MR pipeline

type MRService 

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

MRService handles MR-related operations

func NewMRService 

func NewMRService(cfg *MRConfig, client *Client, ctx *MRContext) *MRService

NewMRService creates a new MR service with injected dependencies.

func NewMRServiceFromEnv 

func NewMRServiceFromEnv(cfg *MRConfig) *MRService

NewMRServiceFromEnv creates a new MR service with dependencies from environment.

func (*MRService) IsEnabled 

func (s *MRService) IsEnabled() bool

IsEnabled returns true if MR integration is enabled

func (*MRService) UpsertComment 

func (s *MRService) UpsertComment(body string) error

UpsertComment creates or updates the terraci comment on the MR

type Pipeline 

type Pipeline struct {
	Stages    []string          `yaml:"stages"`
	Variables map[string]string `yaml:"variables,omitempty"`
	Default   *DefaultConfig    `yaml:"default,omitempty"`
	Jobs      map[string]*Job   `yaml:"-"` // Jobs are added inline
	Workflow  *Workflow         `yaml:"workflow,omitempty"`
}

Pipeline represents a GitLab CI pipeline

func (*Pipeline) ToYAML 

func (p *Pipeline) ToYAML() ([]byte, error)

ToYAML converts the pipeline to YAML

type Reports 

type Reports struct {
	Terraform []string `yaml:"terraform,omitempty"`
	JUnit     []string `yaml:"junit,omitempty"`
	Cobertura []string `yaml:"cobertura,omitempty"`
}

Reports represents artifact reports

type Rule 

type Rule struct {
	If      string   `yaml:"if,omitempty"`
	When    string   `yaml:"when,omitempty"`
	Changes []string `yaml:"changes,omitempty"`
}

Rule represents a job rule

type Secret 

type Secret struct {
	Vault     *VaultSecret `yaml:"vault,omitempty"`
	VaultPath string       `yaml:"-"` // For shorthand format
	File      bool         `yaml:"file,omitempty"`
}

Secret represents GitLab CI secret from external secret manager

func (Secret) MarshalYAML 

func (s Secret) MarshalYAML() (any, error)

MarshalYAML implements custom marshaling to support vault shorthand format

type SummaryJobConfig 

type SummaryJobConfig struct {
	// Image for the summary job (must contain terraci binary)
	Image *Image `yaml:"image,omitempty" json:"image,omitempty" jsonschema:"description=Docker image for summary job (must contain terraci)"`
	// Tags for the summary job runner
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" jsonschema:"description=Runner tags for summary job"`
}

SummaryJobConfig contains settings for the summary job

type VaultEngine 

type VaultEngine struct {
	Name string `yaml:"name"`
	Path string `yaml:"path"`
}

VaultEngine represents Vault secrets engine configuration

type VaultSecret 

type VaultSecret struct {
	Engine *VaultEngine `yaml:"engine,omitempty"`
	Path   string       `yaml:"path,omitempty"`
	Field  string       `yaml:"field,omitempty"`
}

VaultSecret represents a secret from HashiCorp Vault Can be either full object syntax or string shorthand

type VaultSecretShorthand 

type VaultSecretShorthand string

VaultSecretShorthand is used for string shorthand format in YAML output

type Workflow 

type Workflow struct {
	Rules []Rule `yaml:"rules,omitempty"`
}

Workflow controls when pipelines are created

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.