CI/CD pipeline guide

This page describes the checks and publishing jobs that run when you push to GitLab, and how to change them. The pipeline is defined in .gitlab-ci.yml.

tip

If you're not comfortable editing the CI/CD pipeline, ask a Tech Team member for assistance.

Jobs

Job	Description	Default
validate prose	Runs Vale against the docs and stores a report artifact.	On. Allowed to fail without blocking later jobs.
build docusaurus	Builds the documentation site.	On. Required.
test html output	Runs htmltest on the built HTML.	On. Required before preview publish.
release nginx image	Packages the site for the 3di preview webserver.	On for feature branches only.
deploy to auth	Publishes a preview URL on the 3di webserver.	On for feature branches only.
terminate auth	Stops that preview.	Manual. Feature branches only.
prepare for production	Copies the built site for Azure.	Off. Commented out.
deploy to staging	Publishes to Azure staging.	Off. Commented out.
deploy to live	Publishes to Azure live.	Off. Commented out. Manual when enabled.

Processes for the authoring branch and main branch

Authoring branch
  → Vale → Build → HTML test → Preview on 3di auth webserver

Main branch
  → Vale → Build → HTML test

Preview URLs for authoring branches use this pattern:

https://<branch-name>.<project-name>.projects.3di-info.com

Customising Vale

Job: validate prose

Goal	Action
Keep Vale non-blocking	Leave allow_failure: true on validate prose.
Make Vale blocking	Set allow_failure: false, or remove the allow_failure line.
Turn Vale off	Comment out the validate prose job, or add rules: [when: never].
Change which folder is linted	Edit VALE_CONTENT_DIR at the top of .gitlab-ci.yml. The template uses docs.
Change writing rules	Edit .vale.ini. That is separate from enabling or disabling the job.

After the job runs, open the pipeline, select validate prose, and download the Vale report artifact.

For the complete guide on using Vale at 3di, see Using Vale.

Changing HTML tests

Job: test html output. Settings for what is checked are in .htmltest.yml.
For more information, see Configuring Vale and HTML tests.

Goal	Action
Keep HTML tests blocking	Leave the job as it is.
Turn HTML tests off	Comment out test html output and remove - test html output from every needs: list that names it, including release nginx image and any Azure jobs you enable later.
Allow HTML tests to fail without blocking	Add allow_failure: true under test html output.
Ignore empty image alt	Already set in .htmltest.yml as IgnoreAltMissing: true.

warning

If you disable test html output but leave it in a needs: list, GitLab reports a missing required job.

Changing the preview publishing

Jobs: release nginx image, deploy to auth, terminate auth

Goal	Action
Keep previews on feature branches	Leave the rules: that exclude the default branch.
Preview the default branch as well	Change those rules: so the jobs also run on the default branch. Default-branch publishing is intended for Azure once that is set up.
Turn previews off	Comment out release nginx image, deploy to auth, and terminate auth.

Enabling Azure staging and live

Jobs: prepare for production, deploy to staging, deploy to live

These jobs are commented out. There is no Azure Static Web App for this Docusaurus template yet.

To enable these jobs:

1. Create an Azure Static Web App for the documentation project.
2. In GitLab, go to Settings > CI/CD > Variables and add DEPLOYMENT_TOKEN from that Azure app.
3. In .gitlab-ci.yml, uncomment the Promote stage in the stages: list.
4. Uncomment prepare for production, deploy to staging, and deploy to live.
5. Set the url: values under staging and live to the Azure hostnames.
6. Keep staticwebapp.config.json at the project root.

When enabled, the main branch flow is:

Default branch
  → Vale → Build → HTML test
  → Prepare files for Azure
  → Deploy to staging
  → Deploy to live (manual)

Until then, pushes to the main branch still build and test, without publishing to Azure.

Troubleshooting a pipeline in GitLab

1. Open the project in GitLab.
2. Go to Build > Pipelines.
3. Open the latest pipeline for your branch.
4. Each box is a job. Green succeeded, red failed. Vale is allowed to fail, so it may show as a warning.
5. Open a job to read the log, or download artifacts such as the Vale report.

Related files

File	Role
.gitlab-ci.yml	Pipeline jobs and rules
.vale.ini	Vale rules
.htmltest.yml	htmltest settings
staticwebapp.config.json	Azure Static Web Apps settings
.ref-gitlab-ci.yml	Flare reference pipeline. Not used by this project.