andrew.dunn.dev

switchyard

~3 min
gitlabjenkinscijavamavenmigrationpublic-sector
Group Guide The conversion

switchyard is a worked example of how a platform team builds, tests and ships with GitLab CI/CD, written for people fluent in Jenkins and new to GitLab, one of the exhibits I build at GitLab Public Sector. Its tracks each hold a Java and Maven app, the Jenkinsfile that built it and the GitLab pipeline that builds it.

RISING COMPLEXITYTRACK 1basicsdeclarative, agent,tools block,shell stagesTRACK 2controlsparameters, when,stash, input gate,post actionsTRACK 3fan-outdocker agents,parallel, failFast,matrixTRACK 4multibranchbranch, tag, changeconditions, cron,upstream triggerTRACK 5librarycustom steps froma shared library,loaded at a tagTRACK 6platformscripted,credentials, image,Terraform, kubectl
Each track adds Jenkins constructs to the last
  • The lowest track is declarative: an agent, a tools block and stages of shell steps.
  • Each track above adds constructs: parameters and an input gate; parallel stages and a matrix; branch and tag conditions; a shared library.
  • The top track is scripted: credentials, an Artifactory upload, an image, Terraform behind an input gate, and kubectl from a Kubernetes pod template.

Each track keeps the merge request the flow produced beside the one a person reviewed.

Duo flowconvertsa personreviewsJENKINSJenkinsfileJava, MavenFLOW OUTPUTmerge requestkept as producedREVIEWEDmerge requestmerged on greenSCOREeach construct: as produced • needed a person • no direct equivalentCHANGEeach review edit: fix • setting • substitution • choiceREHEARSALa copy of the lowest track, converted live • control-room resets it to main on a schedule
One track, from Jenkinsfile to reviewed pipeline
  • Convert to GitLab CI/CD, above a Jenkinsfile, starts a GitLab Duo agent flow that opens a merge request with a .gitlab-ci.yml; the track keeps it as produced.
  • A person lands the reviewed pipeline in a second merge request, so the converted and the reviewed pipelines can be read side by side.
  • Each construct is scored (as produced, needed a person, no direct equivalent) and each review change is a fix, a setting, a substitution or a choice.
  • The top track stores no credentials: the job token signs each job in to the package and container registries and Terraform state, and the deploy job creates a throwaway kind cluster.
  • rehearsal is a live copy of the lowest track; control-room resets it.

The guide is where a reader starts.

public APImain commitpagescomponentPROFILEgitlab-profileREADME, conversion,SVG platesSITEguideAstro, the referencedocs templatePUBLISHEDGitLab Pagesrebuilt on eachprofile push
The guide, from profile text to Pages
  • gitlab-profile holds the README, the conversion write-up and the plates; the README puts every construct the Jenkinsfiles use beside the GitLab primitive that carries it.
  • guide, the docs template from the Public Sector reference, reads them over the public API at a main commit and publishes to GitLab Pages through the pipeline catalog’s components.
  • yard-components carries jenkins-library’s steps as CI/CD components.

The sample app and its Jenkinsfiles are synthetic; the conversions and their pipelines are real runs on GitLab.com.