Yaml Configuration
This is an interactive guide for exploring various important properties of the screwdriver.yaml configuration for projects.
You can access information about properties by hovering over the property name.
shared: environment: NODE_ENV: test settings: email: addresses: [test@email.com, test2@email.com] statuses: [SUCCESS, FAILURE] annotations: beta.screwdriver.cd/my-cluster-annotation: my-data beta.screwdriver.cd/executor: k8s-vm screwdriver.cd/cpu: HIGH screwdriver.cd/ram: LOW parameters: region: "us-west-1" az: value: "zone 1" description: "default availability zone" jobs: main: requires: [~pr, ~commit, ~sd@123:main] sourcePaths: ["src/app/", "screwdriver.yaml"] image: node:lts steps: - init: npm install - test: npm test publish: requires: [main] template: node/publish@4.3.1 order: [init, publish, teardown-save-results] steps: - publish: npm install - teardown-save-results: cp ./results $SD_ARTIFACTS_DIR deploy-west: requires: [] image: node:lts environment: DEPLOY_ENV: west steps: - init: npm install - deploy: npm deploy deploy-east: requires: [deploy-west] image: node:lts environment: DEPLOY_ENV: east steps: - init: npm install - deploy: npm deploy finished: requires: [stage@deployment] image: node:lts steps: - echo: echo done stages: deployment: requires: [publish] jobs: [deploy-west, deploy-east] description: This stage is utilized for grouping jobs involved in deploying components to multiple regions.
Requires
A single job name or array of jobs that will trigger the job to run. Jobs defined with "requires: ~pr" are started when a pull request is opened, reopened, or modified. Jobs defined with "requires: ~commit" are started when a PR is merged or a commit/push is made directly to the defined SD branch; also runs when the Start button is clicked in the UI. Jobs defined with "requires: ~sd@123:main" are started by job "main" from pipeline "123". Jobs defined with "requires: [deploy-west, deploy-east] are started after "deploy-west" and "deploy-east" are both done running successfully. "Note: ~ jobs denote an OR functionality, jobs without a ~ denote join functionality.
Source Paths
You can optionally specify source paths that will trigger a job upon modification. In this example, the "main" job will only run if changes are made to things under the "src/app/" directory or the "screwdriver.yaml" file. This feature is only available for Github SCM.
Environment
A set of key/value pairs for environment variables that need to be set. Any configuration that is valid for a job configuration is valid in shared, but will be overridden by specific job configurations.
Settings
Configurable settings for any additional build plugins added to Screwdriver.cd.
Annotations
Annotations is an optional object containing key-value pairs. These can be either pipeline or job-level specifications. Annotation key-value pairs can be completely arbitrary, as in the example, or can modify the execution of the build. Check with your Screwdriver cluster admin to find what annotations are supported to modify your build execution with.
Executor annotation
Used to designate a non-default executor to run the build. Some available executors are `jenkins`, `k8s-vm`
CPU annotation
CPU allocated for the VM if using `k8s-vm` executor. `LOW` is configured by default, and indicates 2CPU memory. `HIGH` means 6CPU.
RAM annotation
RAM allocated for the VM if using `k8s-vm` executor. `LOW` is configured by default, and indicates 2GB memory. `HIGH` means 12GB memory.
Email addresses to send notifications to and statuses to send notifications for.
Parameters
A dictionary consists of key value pairs. `key: string` is a shorthand for writing as `key:value` as shown.
Jobs
A series of jobs that define the behavior of your builds.
Image
This defines the Docker image used for the builds. This value should be the same as you would use for a "docker pull" command.
Steps
Defines the explicit list of commands that are executed in the build, just as if they were entered on the command line. Environment variables will be passed between steps, within the same job. Step definitions are required for all jobs. Step names cannot start with `sd-`, as those steps are reserved for Screwdriver steps. In essence, Screwdriver runs `/bin/sh` in your terminal then executes all the steps; in rare cases, different terminal/shell setups may have unexpected behavior.
Template
A predefined job; generally consists of a Docker image and steps.
Order
Can only be used when "template" is defined. Step names that should be run in a particular order. Will select steps from Template and Steps, with priority given to Steps defined in the job.
Teardown
User-defined steps that will always run at the end of a build (even if the previous steps fail or the build is aborted). Step name always starts with "teardown-".
Stages
A list of stages designed to group jobs with similar purposes.
Jobs in a stage
A list of jobs that belong to a stage. It can consist of one or more jobs.
Empty trigger
A job in a stage could have an empty trigger, indicating that it should run as the initial job in the stage immediately after the list of jobs triggering the stage has finished.
Requires a stage
A job may execute after the completion of a stage, especially following the conclusion of the last job within the stage or after the teardown job if it has been explicitly defined.