Annotations

Annotations is a freeform key/value store, often used to configure pipeline or build execution settings. Annotations may be used as a sandbox for YAML anchors and aliases.

Example

shared:
    template: example/mytemplate@stable
    annotations:
        foo: &bar               # Making an anchor for this configuration
            requires: [~pr, ~commit]
            image: node:lts

jobs:
    main:
        <<: *bar            # Referencing the annotation anchor to use that config for main job
        annotations:
            screwdriver.cd/cpu: HIGH                      # Use HIGH for CPU
            screwdriver.cd/buildPeriodically: H H(4-7) * * *   # Run the job every day sometime between 4:00 am and 7:59 am UTC.

Job-Level Annotations

Job-level annotations are used to modify the properties of the build environment. Job-level annotations can be specified under a specific job, or under shared.

The following annotations are supported by plugins maintained by Screwdriver.cd. Ask your cluster admin which annotations are supported in your Screwdriver cluster.

Please note that beta.screwdriver.cd is deprecated in favor of screwdriver.cd. However, annotations that are prefixed with beta.screwdriver.cd will continue to work for now.

Annotation	Values	Description
screwdriver.cd/buildCluster	Build cluster name to run your build in	You can refer to `<API URL>/v4/buildclusters` for a list of available build clusters. By default, builds will be assigned to the default cluster with field `managedByScrewdriver: true`. You can choose from any default cluster and external cluster that your repo is allowed to use (indicated by the field `scmOrganizations`).
screwdriver.cd/buildPeriodically	A CRON expression with an ‘H’ in the minutes field, e.g. `H 0 * * ` Note:* The first interval is always set to “H” (maximum frequency as once per hour) to avoid large spikes for shared resources. You can test out your cron expression at https://crontab.guru/	This will trigger your job periodically according to the cron expression. For any field in the expression, if you specify `H` (or something like `H/5` or `H(3-7)`), the system will replace it with a value over the specified range based on a hash of the job id. For example, `H(3-5)` will resolve to either 3, 4, or 5. Timezone is in UTC.
screwdriver.cd/collapseBuilds	`true` / `false`	Set it to `true` to collapse all `BLOCKED` builds of the job to the latest build. If you want to apply it to the whole pipeline, set it under `shared`. Default behavior depends on cluster configuration, please check with your cluster admin for that.
screwdriver.cd/cpu	`MICRO` / `LOW` / `HIGH` / `TURBO`	When using a `k8s` executor, this will allow the user to choose between 0.5 (`MICRO`), 2 (`LOW`), 6 (`HIGH`) and 12 (`TURBO`) CPU resources. Default is `LOW`. When using a `k8s-vm` executor, this will allow the user to choose between 1 (`MICRO`), 2 (`LOW`), 6 (`HIGH`), and 12 (`TURBO`) CPU resources. Default is `LOW`.
screwdriver.cd/executor	Ask your cluster admin	This will determine what compute system is used to run the build. For example, set the build to run in a VM, a kubernetes pod, a docker container, or a Jenkins agent.
screwdriver.cd/ram	`MICRO` / `LOW` / `HIGH` / `TURBO`	When using a `k8s` executor, this will allow the user to choose between 1 GB (`MICRO`), 2 GB (`LOW`), 12 GB (`HIGH`) and 16 GB (`TURBO`) RAM. Default is `LOW`. When using a `k8s-vm` executor, this will allow the user to choose between 1 GB (`MICRO`), 2 GB (`LOW`), 12 GB (`HIGH`) and 16 GB (`TURBO`) RAM. Default is `LOW`.
screwdriver.cd/repoManifest	Git repository checkout URL, e.g. `https://github.com/org/repo.git/manifestFilePath.xml#branch` 1. Checkout URL: `https://github.com/org/repo.git` (required) 2. Path to manifest file: `manifestFilePath.xml` (optional, defaults to `default.xml`) 3. Branch name: `#branch` (optional, defaults to `#master`)	Repo is a tool built on top of Git for managing repositories. This value is the checkout URL of a Git repository that contains a repo manifest `xml` file. If this value is specified, Screwdriver will checkout your source code in accordance with the configuration of the `xml` file.
screwdriver.cd/timeout	Number of minutes	This will allow the user to choose the number of minutes a build should timeout after. Default is `90` minutes.
screwdriver.cd/dockerEnabled	`true` / `false`	When using a `k8s` executor, set it to `true`, and a Docker-in-Docker container will come up alongside your build container, enabling Docker builds and running Docker images. In addition to this flag in your yaml, your cluster manager must enable the docker in docker feature. (See cluster-management doc).
screwdriver.cd/dockerCpu	`MICRO` / `LOW` / `HIGH` / `TURBO`	When using a `k8s` executor and Docker is enabled, this will set the compute resources for the Docker container, see the `screwdriver.cd/cpu` annotation above for defaults.
screwdriver.cd/dockerRam	`MICRO` / `LOW` / `HIGH` / `TURBO`	When using a `k8s` executor and Docker is enabled, this will set the memory resources for the Docker container, see the `screwdriver.cd/ram` annotation above for defaults.
screwdriver.cd/coverageScope	`pipeline` / `job`	When using the coverage plugin, this will set the scope for project creation. Default behavior depends on cluster configuration (e.g. `COVERAGE_SONAR_ENTERPRISE`), please check with your cluster admin for that.
screwdriver.cd/displayName	Job name to display in the pipeline graph	You can use any name you like for a job to appear in the pipeline graph, without being limited by the unique constraints of Yaml.
screwdriver.cd/mergeSharedSteps	`true` / `false`	When using a template, set it to `true`, and allow the user to merge steps defined in shared and job. Default is `false`.
screwdriver.cd/manualStartEnabled	`true` / `false`	You will not be able to start from a job in the UI when this is set to `false`. Default is `true`.
screwdriver.cd/terminationGracePeriodSeconds	Number of seconds	This will allow the user to choose the number of seconds a build should wait before aborting to execute the teardown steps. Default is `'60'` seconds and Max is `'120'` seconds. In most cases more than default will not be required.
screwdriver.cd/blockedBySameJob	`true` / `false`	Setting it to `false` will allow builds from same job to run concurrently with a default wait time of 5 minute, waiting time can be specified by setting `screwdriver.cd/blockedBySameJobWaitTime`.
screwdriver.cd/blockedBySameJobWaitTime	Number of minutes	Concurrent builds will have 5 minute of wait time by default, set this annotation to override wait time.
screwdriver.cd/jobDisabledByDefault	`true` / `false`	When writing a Screwdriver yaml file, you might want to prevent people forking or copying the config from running a configured periodic build. The job will be disabled upon creation when this is set to `true`. Default is `false`. The user can go to the Screwdriver UI options page to enable the job.
screwdriver.cd/virtualJob	`true` / `false`	To skip execution of certain jobs, set this to `true`. These jobs will not be executed while processing the workflow for an event, but will proceed with SUCCESS status. Will also skip queueing and execution and builds of its downstream jobs will be immediately created to continue the processing of the workflow. Default is `false`.

Pipeline-Level Annotations

Pipeline-level annotations are used to modify the properties of the entire pipeline. Pipeline-level annotations are under the same level as shared and jobs. Pull requests cannot change these annotations, they need to be in the SCM branch of the pipeline.

Annotation	Values	Description
screwdriver.cd/restrictPR	`none` / `all` / `fork` / `branch`	Prevent PR jobs from running. `none` means no restriction. `all` means all PR jobs will not run. `fork` means PRs from forked repos will not run. `branch` means PRs from branch will not run.
screwdriver.cd/chainPR	`false` / `true`	Default value is `false`. When value is `false` a Pull Request will run only those jobs which has `~pr` in `requires`. When `true`, a Pull Request will run jobs which have `~pr` in requires and also trigger their downstream jobs. Example repo: https://github.com/screwdriver-cd-test/chain-pr-example
screwdriver.cd/pipelineDescription	A pipeline description string	This will display a pipeline description on the pipeline page
screwdriver.cd/useDeployKey	`false` / `true`	Default value is `false`. It must be set to `true` for `git checkout` when running Screwdriver builds in user AWS accounts