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
• type Build
• 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 GetCredentialsByType(credentials []*CredentialConfig, filterType string) []*CredentialConfig
  • func (cc *CredentialConfig) UnmarshalYAML(unmarshal func(interface{}) error) (err error)
• type GitAuthor
• type GitCommit
• type GitConfig
• type Label
• type ListResponse
• type Pagination
• type Pipeline
• type Release
• type ReleaseLog
• type ReleaseParamsConfig
• type ReleaseTarget
• type TailLogLine
• type TrustedImageConfig
  • func FilterTrustedImages(trustedImages []*TrustedImageConfig, stages []*manifest.EstafetteStage) []*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

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

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"`
	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"`
}

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"`

	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"`
	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) []*CredentialConfig

FilterCredentials returns only credentials used by the trusted images

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 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

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

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"`
	Depth        int                      `json:"depth,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"`
}

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

func FilterTrustedImages

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

FilterTrustedImages returns only trusted images used in the stages

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