When it comes to maintaining a large collection of pipelines, there are a lot of jobs that have similar or identical configurations, making it tedious to keep them all up to date and maintained. Today, the Screwdriver team is announcing Templates, which solves the issue of maintaining boilerplate job configurations.
Templates are snippets of predefined code that people can use to replace a job definition in a screwdriver.yaml. A template contains a series of predefined steps along with a Docker image.
In order to create and publish a template to screwdriver, you must create a sd-template.yaml and screwdriver.yaml.
To create a template, create a new repo with a sd-template.yaml file. The file should contain a name, version, description, maintainer email, and a config with an image and steps. You can also use a different name for the yaml file if you want.
Example sd-template.yaml:
name: namespace/name version: '1.3' description: template for testing node maintainer: [email protected] config: image: node:6 steps: - install: npm install - test: npm test
Writing a screwdriver.yaml to publish your template
To validate your template, run the template-validate script from the screwdriver-template-main npm module in your main job to validate your template. This means the build image must have NodeJS and NPM properly installed to use it. To publish your template, run the template-publish script from the same module in a separate job.
By default, the file at ./sd-template.yaml will be read. However, a user can specify a custom path using the env variable: SD_TEMPLATE_PATH.
You can optionally put a tag on specific template version. This must be done by the same pipeline that your template is created by. You will need to provide arguments to the script: name, version, and tag. The version needs to be a string exact version.
Example screwdriver.yaml:
shared: image: node:6 jobs: # the main job is run in pull requests as well main: steps: - install: npm install screwdriver-template-main - validate: ./node_modules/.bin/template-validate environment: SD_TEMPLATE_PATH: ./path/to/template.yaml publish: steps: - install: npm install screwdriver-template-main - publish: ./node_modules/.bin/template-publish - tag: ./node_modules/.bin/template-tag --name template_name --version 1.3.0 --tag stable environment: SD_TEMPLATE_PATH: ./path/to/template.yaml
Create a Screwdriver pipeline with your template repo and start the build to validate and publish it.
To update a Screwdriver template, make changes in your SCM repository and rerun the pipeline build.
A good beginner exercise is to create templates for validating and publishing other templates!
The purpose of templates is to make configuring jobs easier, consistent from pipeline to pipeline, and easy to update without needing to touch every pipeline.
To use a template, define a screwdriver.yaml:
Screwdriver takes the template configuration and plugs it in, so that the screwdriver.yaml becomes:
jobs: main: image: node:6 steps: - install: npm install - test: npm test
Since templates support tagging, template creators can use floating tags like āstableā and ālatestā. This allows consumers of the template to use: template: namespace/name@stable, which will cause the job configuration to automatically update the next time it is run to whatever version of that template is tagged as āstableā.
Wrapping and Replacing Steps
Sometimes a template does almost, but not quite exactly what you need. Users can override any settings in templates with their own values.
Users can override a step by defining their own step with the same name.
jobs: main: template: namespace/[email protected] steps: - test: echo āI will run instead of the templateās test stepā
If you want to add some steps before or after a step defined in a template, you can do this by āwrappingā a step. To do this, define a new step with the same name as an existing step, but with a āpreā and/or āpostā prefix.
jobs: main: template: namespace/[email protected] steps: - pretest: echo āI will run before the test stepā - posttest: echo āI will run after the test stepā
The template discovery page in the Screwdriver UI lists each template that is available in Screwdriver. We have plans to expand this page in the future to display more metadata, along with template search capabilities.
To get to the template discovery page, use the dropdown link for Templates in the header.
This action will take you to the Templates page:
Clicking on the name of an individual template will show you the template detail page. This page includes the configuration of the template and what it will do when used in a build. If there are multiple versions of a template, you can click on a version listed at the bottom of the page to see that versionās configuration.
Example template detail page:
In order to use templates, you will need these minimum versions:
The following people contributed to bring you this feature:
Screwdriver is an open-source build automation platform designed for Continuous Delivery. It is built (and used) by Yahoo. Donāt hesitate to reach out if you have questions or would like to contribute: http://docs.screwdriver.cd/about/support.
