gitlabci

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Mar 29, 2026 License: MIT Imports: 14 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 = ciprovider.Image

Type aliases for shared types — keeps all existing code working via gitlabci.Image etc.

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 = ciprovider.MRCommentConfig

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(_ context.Context, 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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL