contracts

README

Estafette CI

The estafette-ci-contracts library is part of the Estafette CI system documented at https://estafette.io.

Please file any issues related to Estafette CI at https://github.com/estafette/estafette-ci-central/issues

Estafette-ci-contracts

This library has contracts for requests / responses between various components of the Estafette CI system.

Development

To start development run

git clone git@github.com:estafette/estafette-ci-contracts.git
cd estafette-ci-contracts

Before committing your changes run

go test ./...
go mod tidy

Documentation

Index

• func GetCredentialsForTrustedImage(credentials []*CredentialConfig, trustedImage TrustedImageConfig) map[string][]*CredentialConfig
• func IsWhitelistedPipelineForCredential(credential CredentialConfig, fullRepositoryPath string) bool
• func IsWhitelistedPipelineForTrustedImage(trustedImage TrustedImageConfig, fullRepositoryPath string) bool
• func IsWhitelistedTrustedImageForCredential(credential CredentialConfig, trustedImage TrustedImageConfig) bool
• type Build
  • func (build *Build) GetFullRepoPath() string
• type BuildLog
• type BuildLogLine
• type BuildLogStep
• type BuildLogStepDockerImage
• type BuildParamsConfig
• type BuildVersionConfig
• type BuilderConfig
  • func (c *BuilderConfig) GetCredentialsByType(filterType string) []*CredentialConfig
  • func (c *BuilderConfig) GetCredentialsForTrustedImage(trustedImage TrustedImageConfig) map[string][]*CredentialConfig
  • func (c *BuilderConfig) GetTrustedImage(imagePath string) *TrustedImageConfig
• type CIServerConfig
• type ContainerRepositoryCredentialConfig
• type CredentialConfig
  • func AddCredentialsIfNotPresent(sourceCredentials []*CredentialConfig, newCredentials []*CredentialConfig) []*CredentialConfig
  • func FilterCredentials(credentials []*CredentialConfig, trustedImages []*TrustedImageConfig, ...) []*CredentialConfig
  • func FilterCredentialsByPipelinesWhitelist(credentials []*CredentialConfig, fullRepositoryPath string) (filteredCredentials []*CredentialConfig)
  • func FilterCredentialsByTrustedImagesWhitelist(credentials []*CredentialConfig, trustedImage TrustedImageConfig) (filteredCredentials []*CredentialConfig)
  • func GetCredentialsByType(credentials []*CredentialConfig, filterType string) []*CredentialConfig
  • func (cc *CredentialConfig) UnmarshalYAML(unmarshal func(interface{}) error) (err error)
• type DockerNetworkConfig
• type GitAuthor
• type GitCommit
• type GitConfig
• type Label
• type ListResponse
• type Pagination
• type Pipeline
  • func (pipeline *Pipeline) GetFullRepoPath() string
• type Release
  • func (release *Release) GetFullRepoPath() string
• type ReleaseLog
• type ReleaseParamsConfig
• type ReleaseTarget
• type TailLogLine
• type TrustedImageConfig
  • func FilterTrustedImages(trustedImages []*TrustedImageConfig, stages []*manifest.EstafetteStage, ...) []*TrustedImageConfig
  • func FilterTrustedImagesByPipelinesWhitelist(trustedImages []*TrustedImageConfig, fullRepositoryPath string) (filteredTrustedImages []*TrustedImageConfig)
  • func GetTrustedImage(trustedImages []*TrustedImageConfig, imagePath string) *TrustedImageConfig
• type Warning

Functions

func GetCredentialsForTrustedImage

func GetCredentialsForTrustedImage(credentials []*CredentialConfig, trustedImage TrustedImageConfig) map[string][]*CredentialConfig

GetCredentialsForTrustedImage returns all credentials of a certain type

func IsWhitelistedPipelineForCredential

func IsWhitelistedPipelineForCredential(credential CredentialConfig, fullRepositoryPath string) bool

IsWhitelistedPipelineForCredential returns true if WhitelistedPipelines is empty or matches the pipelines full path

func IsWhitelistedPipelineForTrustedImage

func IsWhitelistedPipelineForTrustedImage(trustedImage TrustedImageConfig, fullRepositoryPath string) bool

IsWhitelistedPipelineForTrustedImage returns true if WhitelistedPipelines is empty or matches the pipelines full path

func IsWhitelistedTrustedImageForCredential

func IsWhitelistedTrustedImageForCredential(credential CredentialConfig, trustedImage TrustedImageConfig) bool

IsWhitelistedTrustedImageForCredential returns true if WhitelistedTrustedImages is empty or matches the trusted image Path property

Types

type Build

type Build struct {
	ID                   string                      `json:"id"`
	RepoSource           string                      `json:"repoSource"`
	RepoOwner            string                      `json:"repoOwner"`
	RepoName             string                      `json:"repoName"`
	RepoBranch           string                      `json:"repoBranch"`
	RepoRevision         string                      `json:"repoRevision"`
	BuildVersion         string                      `json:"buildVersion,omitempty"`
	BuildStatus          string                      `json:"buildStatus,omitempty"`
	Labels               []Label                     `json:"labels,omitempty"`
	ReleaseTargets       []ReleaseTarget             `json:"releaseTargets,omitempty"`
	Manifest             string                      `json:"manifest,omitempty"`
	ManifestWithDefaults string                      `json:"manifestWithDefaults,omitempty"`
	Commits              []GitCommit                 `json:"commits,omitempty"`
	Triggers             []manifest.EstafetteTrigger `json:"triggers,omitempty"`
	Events               []manifest.EstafetteEvent   `json:"triggerEvents,omitempty"`
	InsertedAt           time.Time                   `json:"insertedAt"`
	UpdatedAt            time.Time                   `json:"updatedAt"`
	Duration             time.Duration               `json:"duration"`
	ManifestObject       *manifest.EstafetteManifest `json:"-"`
}

Build represents a specific build, including version number, repo, branch, revision, labels and manifest

func (*Build) GetFullRepoPath

func (build *Build) GetFullRepoPath() string

GetFullRepoPath returns the full path of the build repository with source, owner and name

type BuildLog

type BuildLog struct {
	ID           string         `json:"id,omitempty"`
	RepoSource   string         `json:"repoSource"`
	RepoOwner    string         `json:"repoOwner"`
	RepoName     string         `json:"repoName"`
	RepoBranch   string         `json:"repoBranch"`
	RepoRevision string         `json:"repoRevision"`
	BuildID      string         `json:"buildID"`
	Steps        []BuildLogStep `json:"steps"`
	InsertedAt   time.Time      `json:"insertedAt"`
}

BuildLog represents a build log for a specific revision

type BuildLogLine

type BuildLogLine struct {
	LineNumber int       `json:"line,omitempty"`
	Timestamp  time.Time `json:"timestamp"`
	StreamType string    `json:"streamType"`
	Text       string    `json:"text"`
}

BuildLogLine has low level log information

type BuildLogStep

type BuildLogStep struct {
	Step         string                   `json:"step"`
	Depth        int                      `json:"depth,omitempty"`
	Image        *BuildLogStepDockerImage `json:"image"`
	RunIndex     int                      `json:"runIndex,omitempty"`
	Duration     time.Duration            `json:"duration"`
	LogLines     []BuildLogLine           `json:"logLines"`
	ExitCode     int64                    `json:"exitCode"`
	Status       string                   `json:"status"`
	AutoInjected bool                     `json:"autoInjected,omitempty"`
	NestedSteps  []BuildLogStep           `json:"nestedSteps,omitempty"`
	Services     []BuildLogStep           `json:"services,omitempty"`
}

BuildLogStep represents the logs for a single step of a pipeline

type BuildLogStepDockerImage

type BuildLogStepDockerImage struct {
	Name         string        `json:"name"`
	Tag          string        `json:"tag"`
	IsPulled     bool          `json:"isPulled"`
	ImageSize    int64         `json:"imageSize"`
	PullDuration time.Duration `json:"pullDuration"`
	Error        string        `json:"error,omitempty"`
	IsTrusted    bool          `json:"isTrusted,omitempty"`
}

BuildLogStepDockerImage represents info about the docker image used for a step

type BuildParamsConfig

type BuildParamsConfig struct {
	BuildID int `json:"buildID"`
}

BuildParamsConfig has config specific to builds

type BuildVersionConfig

type BuildVersionConfig struct {
	Version       string  `json:"version"`
	Major         *int    `json:"major,omitempty"`
	Minor         *int    `json:"minor,omitempty"`
	Patch         *string `json:"patch,omitempty"`
	Label         *string `json:"label,omitempty"`
	AutoIncrement *int    `json:"autoincrement,omitempty"`
}

BuildVersionConfig contains all information regarding the version number to build or release

type BuilderConfig

type BuilderConfig struct {
	Action          *string              `json:"action,omitempty"`
	Track           *string              `json:"track,omitempty"`
	RegistryMirror  *string              `json:"registryMirror,omitempty"`
	DockerDaemonMTU *string              `json:"dindMtu,omitempty"`
	DockerDaemonBIP *string              `json:"dindBip,omitempty"`
	DockerNetwork   *DockerNetworkConfig `json:"dindNetwork,omitempty"`

	Manifest *manifest.EstafetteManifest `json:"manifest,omitempty"`

	JobName     *string                    `json:"jobName,omitempty"`
	ReleaseName *string                    `json:"releaseName,omitempty"`
	Events      []*manifest.EstafetteEvent `json:"triggerEvents,omitempty"`

	CIServer      *CIServerConfig      `json:"ciServer,omitempty"`
	BuildParams   *BuildParamsConfig   `json:"buildParams,omitempty"`
	ReleaseParams *ReleaseParamsConfig `json:"releaseParams,omitempty"`

	Git           *GitConfig            `json:"git,omitempty"`
	BuildVersion  *BuildVersionConfig   `json:"buildVersion,omitempty"`
	Credentials   []*CredentialConfig   `yaml:"credentials,omitempty" json:"credentials,omitempty"`
	TrustedImages []*TrustedImageConfig `yaml:"trustedImages,omitempty" json:"trustedImages,omitempty"`
}

BuilderConfig parameterizes a build/release job

func (*BuilderConfig) GetCredentialsByType

func (c *BuilderConfig) GetCredentialsByType(filterType string) []*CredentialConfig

GetCredentialsByType returns all credentials of a certain type

func (*BuilderConfig) GetCredentialsForTrustedImage

func (c *BuilderConfig) GetCredentialsForTrustedImage(trustedImage TrustedImageConfig) map[string][]*CredentialConfig

GetCredentialsForTrustedImage returns all credentials of a certain type

func (*BuilderConfig) GetTrustedImage

func (c *BuilderConfig) GetTrustedImage(imagePath string) *TrustedImageConfig

GetTrustedImage returns a trusted image if the path without tag matches any of the trustedImages

type CIServerConfig

type CIServerConfig struct {
	BaseURL          string `json:"baseUrl"`
	BuilderEventsURL string `json:"builderEventsUrl"`
	PostLogsURL      string `json:"postLogsUrl"`
	APIKey           string `json:"apiKey"`
}

CIServerConfig has a number of config items related to communication or linking to the CI server

type ContainerRepositoryCredentialConfig

type ContainerRepositoryCredentialConfig struct {
	Repository string `yaml:"repository"`
	Username   string `yaml:"username"`
	Password   string `yaml:"password"`
}

ContainerRepositoryCredentialConfig is used to authenticate for (private) container repositories (will be replaced by CredentialConfig eventually)

type CredentialConfig

type CredentialConfig struct {
	Name                     string                 `yaml:"name" json:"name"`
	Type                     string                 `yaml:"type" json:"type"`
	WhitelistedPipelines     string                 `yaml:"whitelistedPipelines,omitempty" json:"whitelistedPipelines,omitempty"`
	WhitelistedTrustedImages string                 `yaml:"whitelistedTrustedImages,omitempty" json:"whitelistedTrustedImages,omitempty"`
	AdditionalProperties     map[string]interface{} `yaml:",inline" json:"additionalProperties,omitempty"`
}

CredentialConfig is used to store credentials for every type of authenticated service you can use from docker registries, to kubernetes engine to, github apis, bitbucket; in combination with trusted images access to these centrally stored credentials can be limited

func AddCredentialsIfNotPresent

func AddCredentialsIfNotPresent(sourceCredentials []*CredentialConfig, newCredentials []*CredentialConfig) []*CredentialConfig

AddCredentialsIfNotPresent adds new credentials to source credentials if they're not present yet

func FilterCredentials

func FilterCredentials(credentials []*CredentialConfig, trustedImages []*TrustedImageConfig, fullRepositoryPath string) []*CredentialConfig

FilterCredentials returns only credentials used by the trusted images

func FilterCredentialsByPipelinesWhitelist

func FilterCredentialsByPipelinesWhitelist(credentials []*CredentialConfig, fullRepositoryPath string) (filteredCredentials []*CredentialConfig)

FilterCredentialsByPipelinesWhitelist returns the list of credentials filtered by the WhitelistedTrustedPipelines property on the credentials

func FilterCredentialsByTrustedImagesWhitelist

func FilterCredentialsByTrustedImagesWhitelist(credentials []*CredentialConfig, trustedImage TrustedImageConfig) (filteredCredentials []*CredentialConfig)

FilterCredentialsByTrustedImagesWhitelist returns the list of credentials filtered by the WhitelistedTrustedImages property on the credentials

func GetCredentialsByType

func GetCredentialsByType(credentials []*CredentialConfig, filterType string) []*CredentialConfig

GetCredentialsByType returns all credentials of a certain type

func (*CredentialConfig) UnmarshalYAML

func (cc *CredentialConfig) UnmarshalYAML(unmarshal func(interface{}) error) (err error)

UnmarshalYAML customizes unmarshalling an EstafetteStage

type DockerNetworkConfig

type DockerNetworkConfig struct {
	Name    string `json:"name"`
	Subnet  string `json:"subnet"`
	Gateway string `json:"gateway"`
}

DockerNetworkConfig has settings for creating a user defined docker network to make service containers accessible by name from other containers

type GitAuthor

type GitAuthor struct {
	Email    string `json:"email"`
	Name     string `json:"name"`
	Username string `json:"username"`
}

GitAuthor represents the author of a commmit

type GitCommit

type GitCommit struct {
	Message string    `json:"message"`
	Author  GitAuthor `json:"author"`
}

GitCommit represents a commit summary

type GitConfig

type GitConfig struct {
	RepoSource   string `json:"repoSource"`
	RepoOwner    string `json:"repoOwner"`
	RepoName     string `json:"repoName"`
	RepoBranch   string `json:"repoBranch"`
	RepoRevision string `json:"repoRevision"`
}

GitConfig contains all information for cloning the git repository for building/releasing a specific version

type Label

type Label struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Label represents a key/value pair as set in a build manifest

type ListResponse

type ListResponse struct {
	Items      []interface{} `json:"items"`
	Pagination Pagination    `json:"pagination"`
}

ListResponse is a container for paginated filtered list items

type Pagination

type Pagination struct {
	Page       int `json:"page"`
	Size       int `json:"size"`
	TotalPages int `json:"totalPages"`
	TotalItems int `json:"totalItems"`
}

Pagination indicates the current page, the size of the pages and total pages / items

type Pipeline

type Pipeline struct {
	ID                   string                      `json:"id"`
	RepoSource           string                      `json:"repoSource"`
	RepoOwner            string                      `json:"repoOwner"`
	RepoName             string                      `json:"repoName"`
	RepoBranch           string                      `json:"repoBranch"`
	RepoRevision         string                      `json:"repoRevision"`
	BuildVersion         string                      `json:"buildVersion,omitempty"`
	BuildStatus          string                      `json:"buildStatus,omitempty"`
	Labels               []Label                     `json:"labels,omitempty"`
	ReleaseTargets       []ReleaseTarget             `json:"releaseTargets,omitempty"`
	Manifest             string                      `json:"manifest,omitempty"`
	ManifestWithDefaults string                      `json:"manifestWithDefaults,omitempty"`
	Commits              []GitCommit                 `json:"commits,omitempty"`
	Triggers             []manifest.EstafetteTrigger `json:"triggers,omitempty"`
	Events               []manifest.EstafetteEvent   `json:"triggerEvents,omitempty"`
	InsertedAt           time.Time                   `json:"insertedAt"`
	UpdatedAt            time.Time                   `json:"updatedAt"`
	Duration             time.Duration               `json:"duration"`
	LastUpdatedAt        time.Time                   `json:"lastUpdatedAt"`
	ManifestObject       *manifest.EstafetteManifest `json:"-"`
}

Pipeline represents a pipeline with the latest build info, including version number, repo, branch, revision, labels and manifest

func (*Pipeline) GetFullRepoPath

func (pipeline *Pipeline) GetFullRepoPath() string

GetFullRepoPath returns the full path of the pipeline repository with source, owner and name

type Release

type Release struct {
	Name           string                    `json:"name"`
	Action         string                    `json:"action,omitempty"`
	ID             string                    `json:"id,omitempty"`
	RepoSource     string                    `json:"repoSource,omitempty"`
	RepoOwner      string                    `json:"repoOwner,omitempty"`
	RepoName       string                    `json:"repoName,omitempty"`
	ReleaseVersion string                    `json:"releaseVersion,omitempty"`
	ReleaseStatus  string                    `json:"releaseStatus,omitempty"`
	Events         []manifest.EstafetteEvent `json:"triggerEvents,omitempty"`
	InsertedAt     *time.Time                `json:"insertedAt,omitempty"`
	UpdatedAt      *time.Time                `json:"updatedAt,omitempty"`
	Duration       *time.Duration            `json:"duration,omitempty"`
}

Release represents a release of a pipeline

func (*Release) GetFullRepoPath

func (release *Release) GetFullRepoPath() string

GetFullRepoPath returns the full path of the release repository with source, owner and name

type ReleaseLog

type ReleaseLog struct {
	ID         string         `json:"id,omitempty"`
	RepoSource string         `json:"repoSource"`
	RepoOwner  string         `json:"repoOwner"`
	RepoName   string         `json:"repoName"`
	ReleaseID  string         `json:"releaseID"`
	Steps      []BuildLogStep `json:"steps"`
	InsertedAt time.Time      `json:"insertedAt"`
}

ReleaseLog represents a release log for a specific release

type ReleaseParamsConfig

type ReleaseParamsConfig struct {
	ReleaseName   string `json:"releaseName"`
	ReleaseID     int    `json:"releaseID"`
	ReleaseAction string `json:"releaseAction,omitempty"`
	TriggeredBy   string `json:"triggeredBy,omitempty"`
}

ReleaseParamsConfig has config specific to releases

type ReleaseTarget

type ReleaseTarget struct {
	Name           string                            `json:"name"`
	Actions        []manifest.EstafetteReleaseAction `json:"actions,omitempty"`
	ActiveReleases []Release                         `json:"activeReleases,omitempty"`
}

ReleaseTarget contains the information to visualize and trigger release

type TailLogLine

type TailLogLine struct {
	Step         string                   `json:"step"`
	ParentStage  string                   `json:"parentStage,omitempty"`
	Type         string                   `json:"type"`
	Depth        int                      `json:"depth,omitempty"`
	RunIndex     int                      `json:"runIndex,omitempty"`
	LogLine      *BuildLogLine            `json:"logLine,omitempty"`
	Image        *BuildLogStepDockerImage `json:"image,omitempty"`
	Duration     *time.Duration           `json:"duration,omitempty"`
	ExitCode     *int64                   `json:"exitCode,omitempty"`
	Status       *string                  `json:"status,omitempty"`
	AutoInjected *bool                    `json:"autoInjected,omitempty"`
}

TailLogLine returns a log line for streaming logs to gui during a build

type TrustedImageConfig

type TrustedImageConfig struct {
	ImagePath               string   `yaml:"path" json:"path"`
	RunPrivileged           bool     `yaml:"runPrivileged" json:"runPrivileged"`
	RunDocker               bool     `yaml:"runDocker" json:"runDocker"`
	AllowCommands           bool     `yaml:"allowCommands" json:"allowCommands"`
	InjectedCredentialTypes []string `yaml:"injectedCredentialTypes,omitempty" json:"injectedCredentialTypes,omitempty"`
	WhitelistedPipelines    string   `yaml:"whitelistedPipelines,omitempty" json:"whitelistedPipelines,omitempty"`
}

TrustedImageConfig allows trusted images to run docker commands or receive specific credentials

func FilterTrustedImages

func FilterTrustedImages(trustedImages []*TrustedImageConfig, stages []*manifest.EstafetteStage, fullRepositoryPath string) []*TrustedImageConfig

FilterTrustedImages returns only trusted images used in the stages

func FilterTrustedImagesByPipelinesWhitelist

func FilterTrustedImagesByPipelinesWhitelist(trustedImages []*TrustedImageConfig, fullRepositoryPath string) (filteredTrustedImages []*TrustedImageConfig)

FilterTrustedImagesByPipelinesWhitelist returns the list of trusted images filtered by the WhitelistedTrustedPipelines property on the trusted images

func GetTrustedImage

func GetTrustedImage(trustedImages []*TrustedImageConfig, imagePath string) *TrustedImageConfig

GetTrustedImage returns a trusted image if the path without tag matches any of the trustedImages

type Warning

type Warning struct {
	Status  string `json:"status"`
	Message string `json:"message"`
}

Warning is used to issue warnings for not following best practices