Pipeline.yml

Pipeline.yml

Pipeline Syntax

Pipeline files are expressed in YAML format.

The schema are available here:

• pipeline-schema-defs.yml shared definitions
• pipeline-schema.yml main pipeline.yml
• pipeline-step-include-schema.yml step include schema
• pipeline-config-include-schema.yml config include schema

The pipeline.yml file and all included files are validated before the pipeline is run against these schemas.

We'll break down each section of the config, then provide a full example.

Pipeline header

All pipeline defintions start off with:

version: "1.0"
pipeline:
  # all pipeline config is nested under here

global

Pipelines must specify a name and base version.

pipeline:
  appName: "my-app"
  appVersion:
    master: 1.0.0
    feature/new_thing: nt.1.2.0

appVersion

Versions are specified by branch. If no version is found for the current branch, the branch name is prepended to the master version.

environment

Besides the Standard Environment Variables, you can specify additional environment variables for use in your app.

Since your pipeline config is processed for variable substitution, this can also be a handy shorthand for commonly used configuration.

pipeline:
  environment:
    ARTIFACTORY: <Your Docker Registry URL>
    plugins: ${ARTIFACTORY}/jenkins/build-container/refactor
    DOCKER_TAG: ${PIPELINE_APP_VERSION}.${PIPELINE_BUILD_NUMBER}

steps

This is the main part of your pipeline, so we've put it in its own section, see: Steps.

But quickly, it's a list of containers with configuration and commands to execute.

pipeline:
  steps:
    - name: "run-gradle-tests"
      image: gradle:5.0-jre8-alpine
      commands:
        - gradle --no-daemon clean test jacocoTestReport

Variable Substitution

Note that we allow simple variable expansion utilizing both system provided variables or user provided environment variables in the following sections of the configuration:

• pipeline
  • environment
  • steps
    • name
    • image

Example Pipeline

version: "1.0"

pipeline:
  appName: jenkins-pipeline
  appVersion:
    master: 1.0.0
  environment:
    ARTIFACTORY: <Your Docker Registry URL>
    plugins: ${ARTIFACTORY}

  steps:
    - name: test
      image: gradle:5.0-jre8-alpine
      commands:
        - gradle --no-daemon clean test jacocoTestReport

    - name: slack-notification
      image: ${plugins}/slack
      secrets:
        - source: pipeline_notifier_slack_hook
          target:
            - SLACK_WEBHOOK
      environment:
        room: "#slack_notification_channel_name"
      commands:
        - python /app/slack.py
      when:
        status: [ success, failure ]

Disabling schema validation

If you need to temporarily disable schema validation, you can pass validation=false in your Jenkinsfile, e.g.

@Library('poet-pipeline@master')

def wf = new com.tmobile.sre.pipeline.Workflow()
wf.start(agent_label: "Linux", validation: false)

Note that if there are legitimate configuration errors in your pipeline.yml, disabling validation may cause other errors during pipeline runtime or undefined behavior.