Authoring Quickstarters

This document describes how you can create your own quickstarter. At the same time, you should be able to find all information required to make changes to an existing quickstarter.

Technically speaking, a quickstarter is just a Jenkins pipeline that fills an existing repository with files. How this is done, and what exactly is run in the pipeline is up to the quickstarter author. Typically though, the pipeline makes use of the quickstarter pipeline from the Jenkins shared library, which removes the need to write lots of boilerplate such as running a agent pod, cloning sources, copying files and pushing at the end to the component repository. The rest of the guide assumes that you are using this pipeline.

As the Jenkins pipeline runs on a Jenkins agent image, you as the author need to pick either an existing agent image (see "Jenkins agent Images" in the navigation on the left), or create your own.

Creating / Modifying a quickstarter

The only technical requirement is to have a Jenkinsfile, but depending on the purpose of the quickstarter, a quickstarter should provide the following:

If you write any custom stages in the quickstarter pipeline, you have access to the pipeline context.

Usually, quickstarters are triggered through the provisioning app. However, in order to try a new quickstarter, or to try changes to an existing quickstarter which are made in a branch, you can use the quickstart-with-jenkins/run.sh script in the BIX-Digital/ods-contrib repository to provision a quickstarter without registering it with the provisioning app. See its help for usage.

Creating / Modifying a Jenkins agent image

It is highly recommended to use the jenkins-agent-base image as a base image. Otherwise it is likely that some features of the shared pipeline don’t work. The jenkins-agent-base image in turn is based on another base image, e.g. provided by RedHat. The easiest way to get started is to look ath other agent images, such as Go and see how that implements its requirements. If you are just building an image for yourself, do the following:

  1. Copy the folder from one of the Jenkins agents to your local machine, and adjust as needed. For sure you’ll need to update the Dockerfile. Also, change the names in the ocp-config folder and delete the Tailorfile in there. Note that the BuildConfig points to a repository and a branch. You will need to push your sources to a matching location.

  2. Create the OpenShift resources in your *-cd project via Tailor, e.g. tailor -n foo-cd --param REPO_BASE=https://bitbucket.example.com/scm --param ODS_IMAGE_TAG=2.x …​

  3. Start a build in the OpenShift web console.

  4. Reference the built image from your Jenkinsfile like this: imageStreamTag: 'foo-cd/jenkins-agent-bar:latest'

If you want to contribute your Jenkins agent image to OpenDevStack, make sure to add documentation according to the agent image template.