Build config reference

To use Sun* CI, all you need is an application codebase hosted in a Git repository, and for your build, test, and deployment scripts to be specified in a file called .sun-ci.yml, located in the root path of your repository.

The .sun-ci.yml file defines the structure and order of the pipelines and determines:

• Each build is created consisting of stages, and each stage will include corresponding jobs.
• All jobs run in the same workspace or not. The workspace can be used to pass along unique data built during a job to other jobs in the same workflow.
• checkout.depth: Specify how many commit fetched from SCM.
• Setup stages define a list of jobs and their run order. It is possible to run jobs concurrently, sequentially, on a schedule, or with a manual job. Stages contain jobs which are defined inside jobs keyword.
• jobs: What to execute by Sun* CI Runner, every job in the same stage will run in parallel with a unique name to distinguish it from other jobs. If only one job in a workflow fails, you will know it is failing in real-time. Instead of wasting time waiting for the entire build to fail and rerunning the entire job set, you can rerun just the failed job.
• Steps of job: Run commands (such as installing dependencies or running tests) and shell scripts to do the work required for your project. You can see more details about job's behavior here.

Configuration example

checkout:
  depth: 10

stages:
- build
- test
- deploy
  
registries:
  registry.gitlab.com:
    username: $NAME
    password: $PASS

jobs:
- name: build php
  stage: build
  image: registry.gitlab.com/sunasteriskrnd/php-workspace:7.4
  registry: registry.gitlab.com
  workspace: shared
  services:
  - image: postgres:12-alpine
    name: postgres-test
    environment:
      POSTGRES_DB: xxx
      POSTGRES_USER: xxx
      POSTGRES_PASSWORD: xxx
  environment:
    APP_ENV: testing
  cache:
  - key: comopser_vendor_$CI_BRANCH
    paths:
    - vendor
  before_script:
  - cp .env.example .env.testing
  - composer install
  - php artisan key:generate
  - php artisan migrate
  script:
  - composer sniff
  - composer test
  after_script:
  - echo "Finish job"
  only:
    branches:
    - master
    events:
    - pull_request
  except:
    branches:
    - develop
    events:
    - push
  artifacts:
    name: app
    paths:
    - app/
    expires_in: 3 days

- name: test:phpunit
  stage: test
  image: sunasteriskrnd/php-workspace:7.4
  workspace: shared
  script:
  - phpunit --coverage-clover ./coverage.xml --log-junit ./junit.xml
  coverage:
    type: clover
    path: coverage.xml
  test_result:
    type: junit
    path: junit.xml  
  depends_on:
    - build php

- name: test:node
  stage: test
  image: node:12-alpine
  workspace: false
  when: manual
  allow_failure: true
  script:
  - yarn
  - yarn lint
  cache:
  - key:
      files:
        - web/yarn.lock
    paths:
      - web/node_modules

- name: Yarn Install use Recipe
  stage: Install
  use: yarn-install
  with:
    key: value
    object:
      nestedObject: nestedObjectValue
    array:
      - item 1
      - item 2

- name: release production
  stage: deploy
  image: sunci/pm2:alpine-8
  script:
  - pm2 deploy production update --force
  release:
    environment: Production
    url: https://example.com
  only:
    branches:
    - master
  except:
    events:
    - pull_request

See more sample

Job configuration parameters

A job is defined as a list of parameters that define the job’s behavior.

The following table lists available parameters for jobs:

key	Description
name	Define a job name
stage	Define a job stage
image	Use docker images (Find our public images here)
use	Define the name of the recipe you will use
with	Overriding the values corresponding to the key in the recipe (with is optional)
registry	Define a private registry
services	Use docker services images
workspace	Define job use shared workspace with other jobs
before_script	Override a set of commands that are executed before job.
script	Shell script which is executed by Runner.
when	Define when to run job
environment	Define environment variables used in job
allow_failure	Define this job fail without impacting stages
after_script	Override a set of commands that are executed after job.
cache	List of files that should be cached between subsequent runs
cache.*.key	Define name of key that should be cached
cache.*.key.files	Define path to files that should be cached
cache.*.paths	Define paths that should be cached
coverage.type	Define type of coverage result file
coverage.path	Define path to coverage result file
artifacts	List of files and directories to upload to build on success
artifacts.*.paths	Path to files and directories to upload to build on success
artifacts.*.expires_in	Expires time of this artifacts
artifacts.*.name	Define name of the file.
release.environment	Define environment of Release.
release.url	Define url of the Release.
only	Limit when jobs are created
only.branches	Limit branch when jobs are created
only.events	Limit events when jobs are created
only.messages	Limit build message when jobs are created
except	Limit when jobs are not created
except.branches	Limit branch when jobs are not created
except.events	Limit events when jobs are not created
except.messages	Limit build message when jobs are not created
depends_on	Define other jobs that a job depends on
test_result	Build details are displayed
test_result.type	Define type of test result
test_result.path	Define path to test result file

Parameter details

stage

stage is defined per-job and relies on stages which is defined globally. It allows to group jobs into different stages, and jobs of the same stage are executed in parallel (subject to certain conditions). For example:

stages:
- build
- test
- deploy

jobs:
- name: job 1
  stage: build
  script:
  - make build dependencies

- name: job 2
  stage: build
  script:
  - make build artifacts

- name: job 3
  stage: test
  script:
  - make test

- name: job 4
  stage: deploy
  script:
  - make deploy

image

Used to specify a Docker image to use for the job. image is the required keyword that a job needs.

image: ruby:2.6

use

Used to specify an existing recipe provided by Sun*CI to use for the job.

- name: Yarn Install use Recipe
  stage: Install
  use: yarn-install

with

Used to override the available values corresponding to the key of the recipe provided by Sun* CI to use according to your job.

- name: Yarn Install use Recipe
  stage: Install
  use: yarn-install
  with:
    key: value
    object:
      nestedObject: nestedObjectValue
    array:
      - item 1
      - item 2

registry

Used to allow pull docker image from private registry. The registry keyword accepts only values that are the names of the registry listed in the global registries.

registries:
  registry.gitlab.com:
    username: $NAME
    password: $PASS

jobs:
- name: Composer Install
  stage: Install
  image: registry.gitlab.com/sunasteriskrnd/php-workspace:7.4
  registry: registry.gitlab.com

workspace

workspace used to specify this job shared workspace for other jobs. workspace can receives values like true/false/shared/none.

- name: test:phpunit
  stage: test
  image: sunasteriskrnd/php-workspace:7.4
  workspace: shared
  script:
  - phpunit --coverage-clover ./coverage.xml

In case workspace has been globally defined in the default block, the workspace of jobs will default to the corresponding value:

default:
  workspace: shared

stages:
- Build
- Test

jobs:
- name: Job 1
  stage: Build
  image: alpine
  workspace: shared
  script:
  - sleep 10

- name: Job 2
  stage: Test
  image: alpine
  workspace: false
  script:
  - echo Hello

services

Used to specify a service Docker image, linked to a base image specified in image.

You can directly define the Docker image the service will link to:

jobs:
- name: build
  stage: build
  image: docker:stable
  services:
  - docker:stable-dind

Or define the service's environment in environment and set a name for the service:

• services.*.name: define name of service.
• services.*.image: define image of service.
• services.*.environment: define environment of service.

jobs:
- name: build
  stage: build
  image: sunasteriskrnd/php-workspace:7.4
  services:
  - image: postgres:12-alpine
    name: postgres-test
    environment:
      POSTGRES_DB: xxx
      POSTGRES_USER: xxx
      POSTGRES_PASSWORD: xxx

In case services has been globally defined in the default block, the services of jobs will default to the corresponding value.

script, before_script and after_script

script is the required keyword that a job needs. It’s a shell script which is executed by the Runner.

before_script is used to define a command that should be run before each job. This must be an array.

after_script is used to define the command that will be run after each job completed, including failed ones. This must be an array.

- name: build
  stage: build
  image: sunasteriskrnd/php-workspace:7.4
  before_script:
    - cp .env.example .env.testing
  script:
    - composer install
  after_script:
    - php artisan key:generate

In case before_script, after_script has been globally defined in the default block, the job will run corresponding to the command defined inside the default block.

default: 
  before_script:
    - echo "before the job runs"
  after_script:
    - echo "after the job is done"
- name: build
  stage: build
  image: sunasteriskrnd/php-workspace:7.4
  script:
    - composer install

when

when is used to implement jobs that are run in case of failure or despite the failure. when can be set to one of the following values:

• on_passed - execute job only when all jobs from prior stages succeed (or are considered succeeding because they are marked allow_failure). This is the default.

• manual - execute job manually.

Only accept define it when its job does NOT use shared workspace.

- name: test:node
  stage: test
  image: node:12-alpine
  workspace: false
  when: manual
  script:
  - yarn lint

allow_failure

Use allow_failure when you want to let a job fail without impacting the rest of the CI suite. When allow_failure is enabled and the job fails, its stage shows an orange warning in the UI.

jobs:
- name: test:node
  stage: test
  image: node:12-alpine
  allow_failure: true
  script:
  - yarn
  - yarn lint

cache

cache is used to specify a list of files and directories which should be cached between jobs.

- name: job 1
  stage: build
  image: sunasteriskrnd/php-workspace:7.4
  before_script:
    - cp .env.example .env.testing
  script:
    - composer install
  cache:
    - key: composer_vendor_$CI_BRANCH
      paths:
        - vendor
- name: test:node
  stage: test
  image: node:12-alpine
  allow_failure: true
  script:
    - yarn
    - yarn lint
  cache:
  - key:
      files:
        - web/yarn.lock
    paths:
      - web/node_modules

• cache.*.paths: directive to choose which files or directories will be cached.
• cache.*.key: directive allows you to define the affinity of caching between jobs, allowing to have a single cache for all jobs, cache per-job, cache per-branch. The cache:key variable can use any of the predefined variables
• cache.*.key.files: similar to cache.*.key but instead of caching a variable, cache.*.key.files will cache files with a specific path.

In case cache has been globally defined in the default block, the corresponding key, files, paths will be cached by default.

default:
  cache:
  - key:
      files:
        - web/yarn.lock
    paths:
      - web/node_modules

environment

environment define environment variables used in job.

jobs:
  - name: build
    stage: build
    image: sunasteriskrnd/php-workspace:7.4
    environment:
      APP_ENV: testing
...

release

release indicates that the job creates a Release.

• release.environment: Must be defined, the Release environment.
• release.url: (Optional) Show url of the Release.

jobs:
- name: release production
  stage: deploy
  image: sunci/pm2:alpine-8
  script:
  - pm2 deploy production update --force
  release:
    environment: Production
    url: https://example.com

only / except

only and except are two parameters that set a job policy to limit when jobs are created:

• Use only to define when a job runs.
• Use except to define when a job does not run.

Three keywords can be used with only and except:

• branches: defines the names of branches.
  • Possible inputs: An array including any number of:
    • Branch names, for example main or my-feature-branch.
    • Regular expressions that match against branch names, for example /feature-.*/.
• events: defines the events of branches for which the job will run or will not run.
  • Possible inputs: An array including any number of:
    • Github events like pull_request and push events
    • Gitlab events like merge_request and push events.
• messages: defines the message of build for which the job will run or will not run.

jobs:
  - name: build
    stage: build
    image: sunasteriskrnd/php-workspace:7.4
    only:
      branches:
        - develop
        - master
        - /feature-.*/
      events:
        - push
    except:
      branches:
        - branch_1
        - branch_2
      events:
        - pull_request

  - name: test
    stage: test
    image: sunasteriskrnd/php-workspace:7.4
    only:
      branches:
        - test
      events:
        - push
    except:
      branches:
        - develop
        - master
      events:
        - pull_request
      messages:
        - '[ci skip test]'

  - name: production deploy
    stage: deploy
    image: sunasteriskrnd/php-workspace:7.4
    only:
      branches:
        - master
    except:
      events:
        - pull_request
      messages:
        - '[ci skip deploy]'

artifacts

artifacts is used to specify a list of files and directories that are attached to the job. artifacts include name, path, and expires_in:

• artifacts.name: Use the name directive to define the name of the created artifacts archive.
• artifacts.paths: Paths are relative to the project directory.
• artifacts.expires_in: Specify how long artifacts are active before they expire and are deleted.

jobs:
- name: Build php
  stage: build
  image: sunasteriskrnd/php-workspace:7.4
  script:
  - composer sniff
  - composer test
  artifacts:
    name: app
    paths:
    - app/
    expires_in: 3 days

coverage

Use coverage to configure how code coverage is extracted from the job output. coverage must have type & path:

• coverage.type: Define which type of coverage result file. Currently, Sun* CI only supports 2 types includes clover & cobertura in XML format.
• coverage.path: Define where to find coverage result file.

- name: test:phpunit
  stage: test
  image: sunasteriskrnd/php-workspace:7.4
  workspace: shared
  script:
  - phpunit --coverage-clover ./coverage.xml --coverage-html=coverage
  coverage:
    type: clover
    path: coverage.xml

depends_on

depends_on is used to define other jobs that a job depends on. Dependent job will be created if the job in depends_on is created. depend_on only works if the jobs in that job's depends_on belong to another stage.

stages:
- Build
- Test

jobs:
- name: Sleep
  stage: Build
  image: alpine
  script:
  - sleep 10

- name: Wake up
  stage: Build
  image: alpine
  script:
  - echo Hello

- name: Sleep again
  stage: Test
  image: alpine
  script:
  - sleep 10
  depends_on:
    - Sleep

test_result

Use test_result to configure how build details are displayed from the job output. test_result must have type & path:

• test_result.type: Define which type of test result. Currently, SUN* CI only supports Junit in XML format.
• test_result.path: Defind where to find test result file.

- name: test result
  stage: test
  image: sunasteriskrnd/php-workspace:7.4
  script:
  - phpunit --log-junit test_result/junit.xml
  test_result:
    type: junit
    path: test_result/junit.xml