Welcome to IceCI’s documentation!

Welcome to IceCI`s documentation!

Introduction

Concept

IceCI is a continuous integration system designed for Kubernetes from the ground up. Running in the cluster, it operates on Kubernetes primitives while providing a layer of abstraction to make creating and maintaining pipelines more accessible. It also provides a web UI for visualization and easy monitoring of pipeline runs.

First steps

New to IceCI, want to find out what’s it all about? Our quickstart tutorial will guide you through installation and basic pipeline configuration. Start running builds in less than 15 minutes!

• Getting started: Quickstart

Installation and configuration

Learn more about IceCI’s components and the way they’re deployed and configured in the cluster.

• How to install IceCI: Installation

• Advanced configuration options: Configuration

Pipeline reference

Learn about the structure of the pipeline configuration file, its building blocks and available options.

• How to build pipeline files: Building pipelines

• Pipeline config file reference: Pipeline structure

• Environment variables reference: Environment

Quickstart

This tutorial will help you install IceCI in your Kubernetes cluster and set up your first pipeline using an example repository in less than 15 minutes. Let’s start integrating!

Note

To make this quickstart guide actually quick we’ll fork an example public repository, so no secret configuration will be needed.

Prerequisites

Before installing IceCI you’ll need to have access to a Kubernetes cluster. If you’re using an existing cluster in the cloud or on-premise, you’re pretty much good to go. You can also launch IceCI in a local cluster using Minikube or K3s with k3sup. In that case just follow the installation instructions provided by the respective documentation.

Note

When using Minikube you will need to enable the ingress addon to be able to reach the UI. It can be enabled with minikube addons enable ingress. For more information please refer to the documentation.

Installing and running IceCI

Prepare an IceCI namespace

Note

This step is optional - if you’d rather run IceCI in the default namespace, go ahead and skip to the next step.

Create a namespace in which IceCI will operate and update your kubectl config to use that namespace.

kubectl create ns iceci
kubectl config set-context --current --namespace=iceci

Installing IceCI

You can use a handy all-in-one manifest to install IceCI. Applying it in your cluster will set up all the necessary objects to run the applications.

kubectl apply -f https://raw.githubusercontent.com/IceCI/IceCI/master/manifests/crds.yaml
kubectl apply -f https://raw.githubusercontent.com/IceCI/IceCI/master/manifests/minikube.yaml

Once all the applications are running, you’re all ready to go.

Note

Apart from the minikube file, kustomize files for all components, and examples of setup can be found as separate files in the IceCI GitHub repository

Configuring the repository

Now you can access the UI through your browser and add a repository to start running pipelines. To do that, simply click the + button on the top of the left navigation bar and create a new repository using the form.

Note

When using Minikube, you can open the UI by running command minikube service iceci-web

For the purposes of this guide, we’ll fork the quickstart example repository. After forking this repository, all you need to do is copy the clone url and paste it into the Repository URL field in the form.

Note

The example repository is also a template, so instead of forking you can use it to create a new one!

Once the repository is added to IceCI you’re all set. IceCI will react to Git events, so all that’s left is to push a commit to trigger a new pipeline. Try it for yourself!

Next steps

As you can see, the example pipeline is very simple - just to get you acquainted with the structure of the config file. For more information about the configuration file - check out the Pipelines section of the documentation. We’ve also prepared couple of small example applications along with a ready pipeline which you can find on github:

• Python Flask API

• Go Gin API

Overview

IceCI pipelines are defined in .iceci.yaml file stored in root of your Git repository.

Keep in mind - after adding a repository containing a pipeline definition to IceCI, the system won’t build anything until a Git event occurs.

The repository is scanned for new events every minute - when a new event is recorded, a build is triggered. The build is performed based on the contents of the pipeline definition file.

Attention

Currently the only supported Git events are commits. Support for tags and pull requests will be added in future versions.

Building pipelines

Building blocks

There are a couple of key elements in IceCI pipelines. Some of them may be familiar from other continuous integration systems.

Steps

Overview

Steps are the bread and butter of every pipeline. They are operations that will be executed during the pipeline execution. Steps are run in the order defined in the steps field in pipeline spec.

When one of the steps fail, failure handlers are executed and the pipeline finishes. No other steps in the pipeline will run.

Note

Currently IceCI does not support parallel pipeline execution. This feature is considered for future versions.

Every step is executed in a container, running as a pod in Kubernetes cluster. Every step has the same volume mounted in the /workspace directory inside the container running the step. This volume contains source code related to the Git event that occurred in the git repository. The volume is persistent across the whole pipeline and is isolated from other pipelines.

Note

If you create files in the /workspace directory in any of your steps during pipeline execution, all the subsequent steps will have access those files.

Examples

Simple steps

Here’s an example of a working pipeline having 2 simple container run steps.

steps:
- name: step1
  containerRun:
    image: busybox
    script: "echo 'Hello world!'"

- name: step2
  containerRun:
    image: busybox
    script: |
      echo "step 2"
      env

Persistent workspace

An example of generating a file and then accessing it in next step.

steps:
- name: generate-date
  containerRun:
    image: busybox
    script: "date > date.log"

- name: print-date
  containerRun:
    image: busybox
    script: "cat date.log"

Environment variables

Here’s an example of passing environment variables to a container.

steps:
- name: env-test
  containerRun:
    image: busybox
    script: "printenv ENV_VAR_1"
    environment:
    - name: ENV_VAR_1
      value: test-value

Note

As you can see, the environment variable value is hardcoded into the pipeline. This is fine if your build configuration doesn’t contain passwords or other sensitive data. For more information on how to manage sensitive data in IceCI see secrets section.

Files

Here’s an example of mounting files from a secret in a container.

steps:
- name: file-test
  containerRun:
    image: busybox
    script: "cat /mnt/file"
    files:
    - path: /mnt/file
      fromSecret: file-secret

Note

The content of a file can’t be defined inline. Every file has to have a reference to a secret, from which the content is pulled.

Conditional execution

You can control which Git events trigger the execution of your step, here’s an example.

steps:
- name: step1
  when:
    event: ["commit"]
    branch: ["master"]
    skipBranch: ["development", "feature-*"]
  containerRun:
    image: busybox
    script: "echo 'Hello world!'"

Further reading

For more information about steps and their specification see Step

Services

Overview

A service in IceCI is a container that is running during the whole pipeline execution. Services let you run backing containers for your pipeline - for example a PostgreSQL database for your integration tests.

Every service has a name - in the pipeline it can be resolved using this name. If you create a website service, running curl http://website command in your pipeline step will hit the website service assuming that it’s a container listening on port 80 (like nginx, for example).

Note

The pipeline will stop all services after finishing - regardless of the pipeline result.

Warning

If a service stops during the pipeline execution, the pipeline will fail no matter what was the exit code of the service main process.

Examples

Hitting an nginx service

Below is an example of a working pipeline running a website service and a step1 step that will curl the nginx container running as the website service.

services:
- name: website
  image: nginx

steps:
- name: step1
  containerRun:
    image: iceci/utils
    script: "curl http://website/"

Further reading

Service reference can be found in the service section.

Failure handlers

Overview

Failure handlers are very similar to container run steps. They will execute a set of commands in a container. The main difference is that they are used to execute code after a pipeline step fails. This allows you to add cleanup and notification actions to the pipeline.

Failure handlers are defined globally, and can be referenced on both global pipeline level and on step level. Thanks to that, you can create a global error notification, but also add certain cleanup logic to specific steps.

Failure handlers are executed in order of appearance of the onFailure section of the pipeline. Failure handlers for steps are executed first, followed by failure handlers defined in the global section.

Important

When multiple failure handlers are specified, and one of them fails, the other ones will continue to execute. The pipeline tries to run every failure handler ignoring statuses of the previous ones.

Important

Failure handlers don’t affect the status of the pipeline. If a step fails, but all failure handlers finish correctly, the pipeline will still be in failed status!

Examples

Single failure handler

Below is an example of running a failure handler after a failed step. It also shows how environment variables are injected to every step and failure handler in the pipeline.

steps:
- name: step-that-fails
  containerRun:
    image: busybox
    script: "noSuchCommand"
  onFailure:
  - handlerName: failure-handler-1

failureHandlers:
- name: failure-handler-1
  image: busybox
  script: 'echo "step $ICECI_FAILED_STEP_NAME has failed"'

Global failure handlers

Below is an example of running a failure handlers from both step and pipeline level.

steps:
- name: step-that-fails
  containerRun:
    image: busybox
    script: "noSuchCommand"
  onFailure:
  - handlerName: failure-handler-1
  - handlerName: failure-handler-2

globals:
  onFailure:
  - handlerName: failure-handler-1
  - handlerName: failure-handler-3

failureHandlers:
- name: failure-handler-1
  image: busybox
  script: 'echo "failure handler $ICECI_STEP_NAME"'

- name: failure-handler-2
  image: busybox
  script: 'echo "failure handler $ICECI_STEP_NAME"'

- name: failure-handler-3
  image: busybox
  script: 'echo "failure handler $ICECI_STEP_NAME"'

Note

Notice that failure-handler-1 will run twice because it’s declared in both the global section and in the step. Currently IceCI does not implement any deduplication mechanism for failure handlers.

Environment variables and files

Here’s an example of defining environment variables and files on failure handler level.

steps:
- name: step-that-fails
  containerRun:
    image: busybox
    script: "noSuchCommand"
  onFailure:
  - handlerName: failure-handler-1

failureHandlers:
- name: failure-handler-1
  image: busybox
  script: |
    echo $ICECI_FH
    cat /mnt/file
  environment:
  - name: ICECI_FH
    value: failure-handler-env
  files:
  - path: /mnt/file
    fromSecret: failure-secret

Globals

Overview

Some of the settings that can be specified for steps can also be specified in the globals section - this means that they will be applied to all steps in the pipeline. Thanks to this, you don’t have to redeclare settings (like environment variables) in each step, but set it globally for the whole pipeline instead.

Note

Objects from the global section will be passed to steps in the pipeline only when it makes sense. See the globals reference for more details.

Examples

Environment variables

Below is an example of setting up a global environment variables and overriding them on step level.

globals:
  environment:
  - name: GLOBAL_ENV
    value: global-value

steps:
- name: step1
  containerRun:
    image: busybox
    script: "printenv GLOBAL_ENV"

- name: step2
  containerRun:
    image: busybox
    script: "printenv GLOBAL_ENV"
    environment:
    - name: GLOBAL_ENV
      value: local-value

Files

Here’s an example of setting up a global file and overriding it on step level.

globals:
  files:
  - path: /mnt/file
    fromSecret: global-secret

steps:
- name: step1
  containerRun:
    image: busybox
    script: "cat /mnt/file"

- name: step2
  containerRun:
    image: busybox
    script: "cat /mnt/file"
    files:
    - path: /mnt/file
      fromSecret: local-secret

Additional options

Secrets

Overview

Secrets are objects in IceCI responsible for storing sensitive data. They are stored as secrets in Kubernetes cluster. Currently IceCI distinguishes 4 types of secrets:

• generic secret

• docker secret

• git ssh key secret

• git token secret

Attention

git ssh key and git token secret types are used for cloning the repository and are never directly referred to in the pipelines. They can be only used while creating repositories in the UI.

Note

Currently secrets can only be configured through the UI in the settings section.

Generic secret

Generic secrets store sensitive data that can be used in pipelines. Those values can be passed as environment variables to containers. Generic secrets can be used in containerRun steps, services and failure handlers. They can be also defined in the global scope of the pipeline.

Example

Here’s an example of passing a value from generic-secret as an environment variable ENV_FROM_SECRET.

steps:
- name: step1
  containerRun:
    image: busybox
    script: |
      printenv ENV_FROM_SECRET
    environment:
    - name: ENV_FROM_SECRET
      fromSecret: generic-secret

Here’s an example of passing a value from generic-secret to both service and containerRun step in the pipeline via the global section.

globals:
  environment:
  - name: ENV_FROM_SECRET
    fromSecret: generic-secret

services:
- name: envcheck
  image: busybox
  script: |
    printenv ENV_FROM_SECRET
    sleep 99999

steps:
- name: step1
  containerRun:
    image: busybox
    script: |
      printenv ENV_FROM_SECRET

Further reading

For more information about passing secrets as environment variables see environment variable reference.

Docker secret

Overview

A Docker secret stores credentials used to communicate with docker registries. It can be used for both downloading images from private registries as well as pushing images after building them in the containerBuild step. In both cases the dockerSecret field is used.

A Docker secret can also be specified in the globals section of the pipeline - this way it’ll be passed to every object that has a dockerSecret field. If a Docker secret is specified at the object level, it will override the global docker secret.

Examples

Here’s an example of using a Docker image from a private registry to run both the service and step in the pipeline.

services:
- name: db
  image: mrupgrade/private:db
  dockerSecret: dockerhub

steps:
- name: step1
  containerRun:
    image: mrupgrade/private:debian10
    dockerSecret: dockerhub
    script: "echo Hello world"

Note

While running this example in your own pipelines, remember to change the image value into a repository and image that you have read access to. You also need to create a correct Docker secret with name dockerhub.

Here’s an example of setting up dockerSecret at the global level so it doesn’t have to be repeated in every step, service and failure handler.

globals:
  dockerSecret: dockerhub

services:
- name: db
  image: mrupgrade/private:db

steps:
- name: step1
  containerRun:
    image: mrupgrade/private:debian10
    script: "echo Hello world"

Note

While running this example in your own pipelines, remember to change the image value into a repository and image that you have read access to. You also need to create a correct Docker secret with name dockerhub.

Further reading

For more information on how to use Docker secrets check the reference for these pipeline objects: containerRun, containerBuild, service, failureHandler and globals.

Git SSH key

A Git SSH key stores a SSH key used to communicate with a Git server. It’s used for cloning the repository and monitoring any changes that may occur.

The secret is specified while adding a repository to IceCI. After entering a SSH clone URL in the Repository URL field - for example git@github.com:MrUPGrade/example-python-flask-api.git - the Secret names dropdown will show you all the available Git SSH secrets.

Note

Git SSH keys are used whenever the access to repository is via ssh regardless if it’s public or private repository.

Git token

A Git token stores a token used to communicate with the Git server. It’s used for cloning the repository and monitoring any changes that may occur.

The secret is specified while adding a repository to IceCI. After entering a HTTP clone URL in the Repository URL field - for example https://github.com/MrUPGrade/example-python-flask-api.git - the Secret names will dropdown list you all the available Git token secrets.

Note

A Git token is used only when accessing a private repository via https. For public https repositories the token can be skipped and no secrets are needed.

Files

Overview

Each of the step containers can have a number of files mounted - those files can be accessed from within the step script. Files are strictly connected with secrets, as their content is taken from the content of the secrets. The mount path provided in the secret has to be an absolute path.

Note

File content can’t be provided inline - it has to reference an already existing secret. The secret must be of generic type.

Example

Here’s an example of mounting a file into a pipeline step. Keep in mind that the generic content secret has been created using the IceCI UI and is available in the cluster.

steps:
- name: step1
  containerRun:
    image: busybox
    files:
    - path: /var/myfile
      fromSecret: content
    script: |
      cat /var/myfile

Interpolation

Overview

Interpolation syntax was introduced in IceCI to allow pipelines to use the pipeline context for some of the operations. The interpolation works only on selected fields in the pipeline. We do not support any templating of the yaml file itself.

Currently the fields supporting interpolations are:

• ContainerBuild:

  • tags

  • buildArgs

• ServiceRun:

  • image

In fields supported by interpolation syntax, the part inside {{ and }} is interpreted and treated as a name of the field. During the pipeline run it’ll be replaced with the value of the specified field. The rest of the string will not change. Thanks to that you can embed pipeline context into part of the string.

Here are examples of using interpolation to create a Docker tag containing the name of the build and a service created from a Docker image with that build. Notice that you can use the interpolation variable along with a plain string. For example, in the container build step, if the build number was 42, the first pushed tag would be build-42 - the other one will be latest.

steps:
- name: pipeline-context
  containerBuild:
    dockerSecret: dockerhub
    user: iceci
    imageName: my-app
    tags:
    - "build-{{ ICECI_BUILD_NUMBER }}"
    - latest
    buildArgs:
    - name: BRANCH
      value: "{{ ICECI_GIT_BRANCH_NAME }}"
- name: pipeline-service
  serviceRun:
    name: example-service
    image: "myapp:build-{{ ICECI_BUILD_NUMBER }}"
    dockerSecret: dockerhub

Available variables

Note

Although this list is similar to the list of environment variables, these are actually two independent sets of variables - they just happen to share some values.

ICECI_BUILD_NUMBER

Subsequent number of a build in a repository. This value is unique only in the context of a given repository.

Example value: 12

ICECI_GIT_EVENT_TYPE

Git event type. Currently only commit is supported.

Example value: commit

ICECI_GIT_BRANCH_NAME

Name of the branch on which the event happened.

Example value: master

ICECI_GIT_TAG

Git tag name. This environment value is set only if ICECI_GIT_EVENT_TYPE is set to tag.

Example value: 0.1.0

ICECI_GIT_COMMIT_SHA

SHA of Git commit.

Example value: 93126518fa6eec3447d1d57c503aeebfd84f23ec

ICECI_GIT_AUTHOR_NAME

Name of the event author.

Example value: iceci

ICECI_GIT_AUTHOR_EMAIL

Email of the event author.

Example value: iceci@iceci.io

ICECI_GIT_AUTHOR_DATE

Date of the event.

Example value: Wed, 5 Feb 2020 01:24:15 +0100

ICECI_GIT_LOG_HEADER

Git log header encoded in base64.

Example value: VXBkYXRlICdSRUFETUUubWQnCg==

ICECI_GIT_LOG_MESSAGE

Git log body (without the header) encoded in base64.

Example value: VXBkYXRlICdSRUFETUUubWQnCg==

ICECI_GIT_EVENT_NAME

The name of the current git branch, tag or pr - the value depends on which type of event triggered the build.

Example value: master

Runtime profiles

Overview

Runtime profiles are configuration sets which can be assigned to specific pipeline steps. They allow for fine-tuning the pod configuration by setting resource requirements or node selectors, as well adding additional information via labels and annotations, among other things. The runtime profiles are Kubernetes custom resources that can be created in the cluster by the administrator. After creation they can be used in the pipelines by all the users. If a pipeline step uses a runtime profile, the specification details of the profile will be copied to the pipeline step pod.

Example

Below is an example of a runtime profile YAML manifest, using all of the possible configuration fields.

apiVersion: iceci.io/v1alpha1
kind: RuntimeProfile
metadata:
  name: example
spec:
  serviceAccountName: myuser
  imageBuilder: buildkit
  nodeSelector:
    kubernetes.io/hostname: iceci-builder
  annotations:
    example/annotation: myvalue
  labels:
    example/label: myvalue
  resources:
    requests:
      cpu: "1"
      memory: 128Mi
    limits:
      cpu: "1"
      memory: 128Mi

Creating and using runtime profiles

Runtime profiles can only be created directly inside the cluster by an administrator. To create a profile, simply prepare the YAML manifest and run kubectl apply.

To apply a runtime profile inside your step, add the runtimeProfile parameter to your step definition in .iceci.yaml

steps:
- name: step1
  runtimeProfile: myprofile
  containerRun:
    image: busybox
    script: "echo 'Hello world!'"

Runtime profile schema

As mentioned, runtime profiles are Kubernetes custom resources and as such, at the top level, they follow the standard CRD schema.

apiVersion: string

The API version of the CRD. The value that should be used is iceci.io/v1alpha1

kind: string

The kind of the CRD. The value that should be used is RuntimeProfile

metadata: map[string]string

The metadata of the CRD. Should contain the name field, but additional values can be added if needed.

spec: Object

The specification of the runtime profile. It may contain any of the following.

serviceAccountName: string

The name of the service account that will be used to run the pipeline step pod.

imageBuilder: string

Name of the library that will be used to build Docker images in ContainerBuild steps. The possible values are kaniko and buildkit. If this parameter isn’t provided, all builds are done using kaniko.

nodeSelector: map[string]string

A map of node labels that will be used to determine which node pipeline step pod will be scheduled onto. This field follows the structure of the Kubernetes native node selector. For more information on node selectors, see the node selector section in the Kubernetes documentation.

annotations: map[string]string

A map of annotations that will be added to the pipeline step pod. For more information on annotations, see the annotations section in the Kubernetes documentation.

labels: map[string]string

A map of labels that will be added to the pipeline step pod. For more information on labels, see the labels section in the Kubernetes documentation.

Note

The iceci/* prefix is used internally by IceCI for both annotations and labels and shouldn’t be used in runtime profiles. Any annotations or labels in the runtime profile spec starting with this prefix will be ignored and won’t be added to the pod.

resources: Object

A set of resource requirements that will be added to the pipeline step pod. This field follows the structure of the Kubernetes native resource requirements. For more information on resource requirements, see the managing resources for containers section in the Kubernetes documentation.

Pipeline structure

Pipeline root object

The root of pipeline yaml file consists of the following fields.

steps: list(Step)

List of Step objects.

For more information and examples on how steps work see steps section.

services: list(Service)

List of Service objects. Services will be created all at once, at the beginning of pipeline.

For more information and examples on how services work see services section.

failureHandlers: list(FailureHandler)

List of FailureHandler objects.

List of all failure handler objects available in the whole pipeline. They can be referenced by both Step or other global failure handlers.

For more information and examples on how failure handlers work see failure handlers section.

globals: object

Globals object contains settings that will be passed down to the relevant objects in the pipeline.

For more information and examples see globals section.

dockerSecret: string

Name of the docker secret used for communicating with docker registry.

This value will be passed to the following objects:

• container run step

• container build step

• failure handler

• service

onFailure: list(FailureHandlerReference)

List of global failure handlers. Those failure handlers will be run after every failed step in the pipeline, no matter what type it was.

environment: list(EnvironmentVariable)

List of environment variables.

Those environment variables will be passed to every Container run step in the pipeline.

Important

Failure handlers have access to all the environment variables of a given step injected into their spec, so they’re available in the failure handler as well.

files: list(File)

List of files that will be mounted in every Container run step in the pipeline.

Important

Like environment variables, files from a given step are also mounted into Failure handlers.

Objects and types

Definitions of all objects and types used in the pipeline definition.

Step: Object

Step is an object in the pipeline representing a single execution unit.

For more information and examples of how steps work see steps section.

name

Name of the step. This name will be displayed in the UI.

onFailure: list(FailureHandlerReference)

List of FailureHandlerReference objects. All of failure handlers will be executed in the order declared in this list. If global failure handlers are also defined, they will be run after those specified here.

when: When

Defines a set of conditions to determine if a step should run for a given Git event. This attribute is optional - if not present, the step will run for every commit and every branch pushed to the repository.

For full reference see When

runtimeProfile: string

The name of a runtime profile that should be applied to the step. For more reference see runtime profiles section

containerRun: ContainerRun

Container run step is used for running various commands in a container.

For full reference see ContainerRun.

containerBuild: ContainerBuild

Container build step is used to build a Docker image and publish it to a specified Docker registry.

For full reference see ContainerBuild.

serviceRun: ServiceRun

Service run step is used for launching a Service type container at a specific moment of the pipeline run. It can be used, for example, to create a service out of an application created in one of the previous pipeline steps.

For full reference see ServiceRun.

waitForAccept: WaitForAccept

Wait for accept step is used for creating conditional builds. This type of step will pause the pipeline execution and wait for user action before continuing. It can be used, for example, to create pipelines that apply new infrastructure changes only after the user accepts them.

For full reference see WaitForAccept.

Important

The containerRun, containerBuild, serviceRun and waitForAccept fields are mutually exclusive - the step must be of a single type. If more than one field will be set, the pipeline will fail during validation.

ContainerRun: Object

Container run executes the script inside a Docker container running a Docker image. If any of the commands exit with code other than 0, the step will fail.

image: string

Docker image used to run your commands.

dockerSecret: string = ""

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string

A string containing the script that will be executed. The shell is run with set -e so this script will fail if any of the commands exits with a code other than 0. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

files: list(File)

List of files that will be mounted in the container.

ContainerBuild: Object

Build the Docker image and pushes it to registry.

registry: string = docker.io

Address of the Docker registry used to store images.

user: string

User used to login to the Docker registry.

imageName: string

Name of the image that will be built. This name is not the full image name, but only the name of a given image without a tag, user and registry.

tags: list(string)

Tags of a Docker image that will be build.

contextPath: string = .

Path that will be used as context in the Docker build process. See docker help command for more information.

Important

The context will be set to ., but the current working directory is set to the workspace folder, so it will behave like the Docker command is run inside the source directory.

dockerfilePath: string = Dockerfile

Path to the Dockerfile file.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

buildArgs: list(BuildArg)

A list of build-time arguments.

ServiceRun: Object

Creates a Service and exits - the service itself, however, will run until the pipeline finishes.

Note

The status of this step reflects the status of creating the service object, but not the status of the service itself.

name: string

The name of the service.

image: string

Docker image used to run the service.

dockerSecret: string = ""

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string

A string containing the script that will be executed inside the service container. The shell is run with set -e so this script will fail if any of the commands exits with a code other than 0. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

files: list(File)

List of files that will be mounted in the container.

WaitForAccept: Object

Pauses the pipeline and waits for user acceptance before continuing. Can be set to an empty object {} (which will cause the pipeline to wait indefinitely for user interaction), or a timeout parameter can be set, to ensure that the pipeline will fail after a certain period of inactivity.

timeout: integer

Number of seconds that the step will wait for user acceptance. When this timeout is exceeded, the step will fail. If not set or set to 0, the step will wait for user acceptance indefinitely.

Service: Object

Service runs an application specified by script inside a Docker image.

name: string

Name of the service that will be used in the UI and also for communicating with the service. This name will be added to /etc/hosts of every step and failure handler in the pipeline, so the service can be resolved using the name.

image: string

Docker image used to run the service.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string = ""

A script or command that will be executed. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

FailureHandler: Object

Failure handler is an object representing a special kind of pipeline execution unit for handling errors in pipeline steps. Its definition is very similar to the container run step.

name: string

Name of the failure handler. This name will be used by FailureHandlerReference

image: string

Docker image used to run the failure handler.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string

A script or command that will be executed. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

files: list(File)

List of files that will be mounted in the container.

FailureHandlerReference: Object

Failure handler reference is an object representing reference to a defined failure handler.

handlerName

Name of the FailureHandler object to run. The failure handler must be defined in the failureHandlers list - else the pipeline will fail during validation.

EnvironmentVariable: Object

The environment variable object represents an environment variable within a container. You can provide a value inline through value or by referencing a secret by its name using fromSecret field.

name

The name of the environment variable that will be passed to the container.

value

Value for a given environment variable.

fromSecret

Name of a secret from which the value should be retrieved to inject to the container as an environment variable.

Note

Currently IceCI supports creating environment variables by explicitly entering their values in the pipeline yaml or by providing a secret name from which the value should be taken. Those options are exclusive for a given variable - you can’t have both value and fromSecret set at the same time - the pipeline validation will fail.

File: Object

The file object represents a file that’ll be mounted in a container from a secret. Unlike environment variables, file values cannot be provided inline - they have to reference a secret.

path

The absolute path that the file will be mounted in.

fromSecret

Name of a secret from which the value should be retrieved to mount into the container as a file.

BuildArg: Object

The BuildArg object represents a build-time parameter that will be set during the build. Equivalent to --build-arg parameter in the docker build command.

name

The name of the build argument

value

The value of the build argument

When: Object

This object defines the conditions determining if the pipeline step should be run for a specific Git event or not.

event: list

A list of event types that the step should run for. Supported values are commit and tag. Optional - if not provided, commit is assumed.

branch: list

A list of branch names that the step should run for. Optional - if not provided, the step will run for all branches.

skipBranch: list

A list of branch names that the step should not run for. Optional - if not provided, the step will run for all branches defined by the branch attribute. In case the branch attribute is also not provided, the step will run for all branches.

Important

The branch and skipBranch attributes will have effect only if the event attribute contains commit or is empty.

tag: list

A list of tag names that the steps should run for. Optional - if not provided, the step will run for all tags.

skipTag: list

A list of tag names that the step should not run for. Optional - if not provided, the step will run for all tags defined by the tag attribute. In case the tag attribute is also not provided, the step will run for all tags.

Important

The tag and skipTag attributes will have effect only if the event attribute contains tag.

Note

The branch, skipBranch, tag and skipTag fields support basic string globbing in their list values. This means that you can use * as a wildcard to match multiple values. For example - if you enter feature-* in the branch list, the step will run for all branches with names starting with feature-

Environment

IceCI generates additional metadata for every build and passes this data to the relevant objects in the pipeline.

Note

In the UI those environment variables won’t be visible in neither step nor failure handler details. They are injected during execution - the UI only shows variables defined in the pipeline.

Steps

Environment variables specified here are injected into every step and failure handler in the pipeline.

ICECI_BUILD_NUMBER

Subsequent number of a build in a repository. This value is unique only in the context of a given repository.

Example value: 12

ICECI_STEP_NAME

Name of the step that’s currently executing

Example value: run-tests

ICECI_SERVICE_XXX

IP address of the XXX service. This variable is created for every service defined in the pipeline spec.

Example value: 10.0.0.1

ICECI_GIT_EVENT_TYPE

Git event type. Currently only commit is supported.

Example value: commit

ICECI_GIT_COMMIT_SHA

SHA of Git commit.

Example value: 93126518fa6eec3447d1d57c503aeebfd84f23ec

ICECI_GIT_BRANCH_NAME

Name of the branch on which the event happened.

Example value: master

ICECI_GIT_TAG

Git tag name. This environment value is set only if ICECI_GIT_EVENT_TYPE is set to tag.

Example value: 0.1.0

ICECI_GIT_LOG_HEADER

Git log header encoded in base64.

Example value: VXBkYXRlICdSRUFETUUubWQnCg==

ICECI_GIT_LOG_MESSAGE

Git log body (without the header) encoded in base64.

Example value: VXBkYXRlICdSRUFETUUubWQnCg==

ICECI_GIT_AUTHOR_NAME

Name of the event author.

Example value: iceci

ICECI_GIT_AUTHOR_EMAIL

Email of the event author.

Example value: iceci@iceci.io

ICECI_GIT_AUTHOR_DATE

Date of the event.

Example value: Wed, 5 Feb 2020 01:24:15 +0100

Failure handler

Environment variables specified here are injected into every failure handler in the pipeline.

ICECI_FAILED_STEP_NAME

Name of the failed step.

Example Value: run-tests

Important

Failure handlers also have all of the failed step environment variables injected - this includes secrets.