WARNING: Jenkins X version 2.x is unmaintained. Do not use it.

Please refer to thev3 documentation for the latest supported version.

Jenkins X Pipeline Syntax Reference

cloud native serverless pipelines

Syntax forjenkins-x.yml and build packs

Where to Define Your Pipelines

Pipelines can either be defined inbuild packs, used formultiple projects, or in thejenkins-x.yml file in a project’s repository.When defining pipelines in a build pack, the top-level configuration below isused directly, while injenkins-x.yml, the top-level configuration is underthepipelineConfig key.

Top-Level Configuration

  • extends - A build pack can extend another build pack,inheriting its configuration and contributing its own additional behavior.
    • file - The name of the build pack to inherit from.
    • import - If the build pack to inherit from is not in the samerepository as this build pack, specify where to import it from.
  • agent - A default agent configuration for all pipelines in thebuild pack or project.
  • env - Environment variables to be made available for allpipelines in the build pack or project.
  • containerOptions - Default configuration for stepcontainers for all pipelines in the build pack or project.
  • pipelines - The pipeline definitions for thisbuild pack or project.

Specifying and Overriding Release, Pull Request, and Feature Pipelines

  • pullRequest,release,feature -The configuration for the three pipeline types for this build pack or project.
    • setup - The first stage to run.
    • setVersion - The second stage to run.
    • preBuild - The third stage to run.
    • build - The fourth stage to run.
    • postBuild - The fifth stage to run.
    • promote - The sixth and final stage to run.
    • pipeline - The full definitionof the pipeline. Mutually exclusive withsetup, etc.
  • overrides - A list of overriding changes to maketo the inherited or default pipeline.
    • pipeline - The name of the pipeline this override should be appliedto (release,pullRequest, orfeature). If unspecified, this overridewill be applied to all pipelines.
    • stage - The name of the stage this override should be applied to.If unspecified, this override will be applied to all stages.
    • name - The name of the step this override should be applied to. Ifunspecified, this override will be applied to all steps.
    • step - A singlestep which will be usedto override the named step or, if no step name is given, all steps in thespecified stage. If neitherstep norsteps is given, all steps inmatching stages in matching pipelines will be removed.
    • steps - One or moresteps which will beused to override the named step or, if no name is given, all steps in thespecified stage.
    • type - Whether thestep orsteps should replace the named step,be prepended before the named step, or be appended after the named step.Possible values arereplace,before, orafter.
    • agent - An agent definition that will replace theexisting agent definition for matching pipelines and stages. Step agentsare not changed.
  • default - A fullpipeline definitionthat will be used for thepullRequest,release, andfeature pipelines ifthey are not already specified.

Build pack stages

  • preSteps - A list of steps to run beforethe main body of steps for this stage.preSteps isnot inherited from parentbuild packs.
  • steps - The main body of steps to run forthis stage. If inheriting from a parent build pack, these steps will be appendedto the parent build pack’ssteps by default.
  • replace - An optional boolean. If true, the inherited stage definition’ssteps will be replaced, rather than appended to.

Defining an Individual Pipeline

Configuration for the Whole Pipeline

  • agent - A default agent definition to use for anystages without their own agents specified.Overridesbuild pack or project agent definition.
  • env - Environment variables set for the entire pipeline, whichcan be overridden in individual stages and steps.
  • options - Additional configuration for the entirepipeline.
    • timeout - The maximum duration for executionof the pipeline, after which the build will be terminated.
      • time - How long to wait until timing out the build.
      • unit - The unit fortime. Can be any ofseconds,minutes,orhours. Defaults toseconds if unspecified.
    • containerOptions - Default configuration forstep containers within this pipeline, overriding any common settings withbuild pack or project default configuration.
    • sidecars - One or moreKubernetes containerswhich will be added to every stage in the pipeline, to provide additionalfeatures in the pods.
    • volumes - One or moreKubernetes volumeswhich will be added to every stage in the pipeline, and can be mounted viacontainerOptions.
  • dir - Optional default working directory for stages andsteps in this pipeline. Can either be relative, under the/workspace/sourcedirectory were the project source will be checked out, or absolute.
  • stages - A list of one or morestages.

Configuration for Stages

  • name - The name of the stage. Required and must beunique.
  • agent - The agent definition to use for this stage,overriding the agent specified forthe whole pipelineif one is specified.
  • options - Additional configuration for the stage.
    • containerOptions - Default configuration forstep containers within this stage, overriding any common settings withthe whole pipeline defaultconfiguration.
    • sidecars - One or moreKubernetes containerswhich will be added to this stage’s pod, to provide additional features.
    • volumes - One or moreKubernetes volumeswhich will be added to this stage’s pod, and can be mounted viacontainerOptions.
  • env - Environment variables set for all steps or nested stages,overriding any variables defined forthe whole pipeline.
  • stages - A list of stages to run sequentiallywithin this stage, inheriting this stage’s configuration. Cannot be used witheithersteps orparallel.
  • parallel - A list of stages to run in parallel,inheriting this stage’s configuration. Cannot be used with eithersteps orstages.
  • dir - Optional default working directory for steps andnested stages. Can either be relative under the/workspace/source directory orabsolute.
  • steps - A list of steps to run in this stage. Cannot be usedwith eitherstages orparallel.

Configuration for Steps

  • name - A name for the step, used in logging and foroverrides.
  • command - The command to execute in this step.
  • args - An array of arguments to the command.
  • dir - Optional working directory for this step.
  • agent - Optional agent configuration for this step.
  • loop - Repeats the nestedstepsfor each value in the specified list.
    • variable - The name of the environment variable to be set with thevalue for this loop iteration.
    • values - A list of strings to iterate over.
    • steps - One or more steps to run foreach iteration of the loop.
  • env - Environment variables set for this step, adding toinherited environment variables from the stage and pipeline.

Common Directives

  • agent - What container image should be used.
    • image - A container image, either as a fully qualified image or apod template name.
    • label - Only used with static Jenkins masters - the Jenkins agentlabel to use.
  • env - One or more environment variables.
    • name - The name of the environment variable.
    • value - The value of the environment variable.
  • containerOptions
    • SeeKubernetes container configuration.name,command,args,image, andworkingDir cannot be specified.
    • Common use cases forcontainerOptions include resource requests andlimits, and volume mounts.

Examples

Full pipeline definition injenkins-x.yml

# If a build pack is specified, the `pipeline` in `release`, `pullRequest`, and `feature` will be ignored.buildPack:nonepipelineConfig:pipelines:release:# While the legacy build pack built-in stages can be used in jenkins-x.yaml, pipeline is preferred.pipeline:# Define a default container image we'll use throughout the pipeline, unless an explicit agent is# specified on a stage or step.agent:image:"some/image@version"# or "maven" - this means "use the maven pod template"# Environment variables are either static key/value pairs or Kubernetes valueFrom EnvVarSources.# See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#envvarsource-v1-core# for more information on valueFrom.# Environment variables defined at the top level can be overridden in stages and individual# steps.environment:          -name:SOME_VARvalue:A value for the env var          -name:SOME_OTHER_VARvalue:Another var          -name:SOME_API_KEYvalueFrom:secretKeyRef:name:mysecretkey:apikey# Options contains other configuration for the pipeline.options:# containerOptions allows specifying more advanced default configuration for the containers# used for all stages and steps in this scope, using the standard Kubernetes syntax for# containers.# See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#container-v1-core.# Not all fields can be configured - e.g., name, command, arguments, image, and dir are all# defined via the syntax - but everything else can be.# Like with environment variables, containerOptions at the top level can be overridden and# added to by stages.containerOptions:# Here we're setting the resource requests and limits for all step containers within this# pipeline.resources:requests:cpu:0.1memory:64Milimits:cpu:0.2memory:128Mi# timeout allows you to set the maximum duration for builds of this pipeline.timeout:time:15unit:minutes# A pipeline must contain at least one stage, and each stage must have a unique name.stages:          -name:Stage With Steps And Options Etc# agent, options, and environment are valid on stages as well. For the parents of nested# sequential or parallel stages, their children inherit the parent's agent, options,# and environment.# options on a stage currently only can contain containerOptions.options:containerOptions:resources:limits:cpu:0.4memory:256Mi# A stage must contain at least one of "steps", "stages", or "parallel"# Steps must contain at least one command to be executed or a loop.steps:              -command:mvn# args are a YAML array, so can be specified either on multiple lines or in a []args:                  -clean                  -installdir:foo# Optional, allows running this step in a subdirectory of the workspace, or# a different absolute directory.# Steps can have their own images specified, overriding the stage and top-level images.agent:image:some-other-image# A loop allows you to specify a list of potential values for an environment variable and a# set of one or more steps. Those steps will be run, sequentially, for each of the# potential values. Loops can also be nested for more complex combinations.              -loop:variable:LANGUAGEvalues:                    -maven                    -gradle                    -nodejssteps:                    -command:echoargs:                        -hello                        -${LANGUAGE}          -name:Stage with nested sequential stages# Any configuration of agent, options, or environment will apply to all child stages.environment:              -name:SPECIFIC_TO_SEQUENTIAL_PARENTvalue:something# A list of nested stages to run sequentially. This is meant to allow for avoiding# copy-pasting configuration across a set of stages that need to have the same configuration# but where that configuration shouldn't be in place for *all* stages in the pipeline.stages:# ...insert stages here. =)          -name:Stage with nested parallel stages# Works very similarly to sequential stages, except that the stages are executed in parallel,# rather than sequentially.parallel:# ...insert stages here. =)

Feedback

Was this page helpful?

Glad to hear it! Pleasetell us how we can improve.

Sorry to hear that. Pleasetell us how we can improve.