Docs tutorial: Demonstrate the process of writing a complete pipeline
Goal
We have a Create and run your first GitLab CI/CD pipeline tutorial already, but it's the absolute minimum possible. It's designed for the person who is completely new to CI/CD in general, and to just see a pipeline run. It uses very few CI/CD features, and has no "real" output.
But many of our users are not new to CI/CD concepts, just new to GitLab CI/CD. They know what they want to do, but not how to do it, so the basic tutorial is not enough for their needs. They need a tutorial that demonstrates all the keywords that they are most likely to use when setting up their first pipeline.
There are some user comments about this in: CI/CD doc-related verbatims from the FY22Q4 SUS (technical-writing#554 - closed)
The common request is essentially for more examples, including "complete" pipelines.
We should create a more fully fledged tutorial that demonstrates the whole process of creating a pipeline that does something realistic.
Outline
As I'm familiar with the process for building a large docs site (gitlab-docs
), which currently uses all the fundamental features of GitLab CI/CD, I propose using that as the real world example, but writing a smaller one from scratch in the tutorial. It should demonstrate:
- The process before creating the pipeline: Defining what we want the pipeline to do, through answering questions. Do we want schedules? Do we want merge request pipelines?
-
workflow: rules
along with the new pipeline name to control the pipeline. This will also introduce CI/CD variables, the most fundamental component in CI/CD pipelines. - A
build
stage, with- A build job that compiles the default page for a popular SSG, like Hugo or Nuxt. The job should save the compiled site in an artifact, for use/testing in the test stage, a ~"group::pipeline insights" component.
- A
test
stage, with:- A job that uses the artifact to run a test, like a link test.
- A job imported from a CI/CD template, like Secrets Detection, a devopssecure feature. Something that has a report artifact that people can review after the pipeline runs.
- A job that uses
needs
to start running immediately, for a test that doesn't need to wait for the artifact.
- A
deploy
stage with:- A job that deploys the site to GitLab Pages, a ~"devops::release" feature.
Nice to have:
- Some
default
config that's useful to have in all jobs, and how to skip that config when needed. - MR pipelines, including how to switch between push and MR pipelines.
- Some jobs with different behavior depending on the pipeline.
- An optional
manual
job, perhaps the link checker? - Tips and tricks
Things to avoid
This tutorial will not:
- Talk too much about Runners. The tutorial will be designed for use on GitLab.com, using shared runners.
- Claim to be "the" way to author a pipeline.
- Use some of the useful, but tricky stuff, like
!reference
tags, multi-line commands, etc. - Use downstream pipelines. Very useful, but would expand the scope of the tutorial too much.
Global nav
This page should be "around" here: https://docs.gitlab.com/ee/ci/quick_start/