Skip to content

Writing Pipelines

This supporting note expands the CI/CD guideline with practical rules for writing maintainable pipeline YAML.

Design goal

Keep pipelines low-complexity and readable. The pipeline should orchestrate build, test, package, and deployment steps, not become the only place where application logic lives.

Default authoring rules

Mandatory

  • Keep business-specific build logic in checked-in scripts, make targets, or build tooling rather than in long inline shell blocks.
  • Keep secrets, credentials, and environment-specific values outside the YAML definition.
  • Keep stages and jobs aligned with delivery intent: build, test, package, publish, deploy.
  • Fail fast on validation problems and stop promotions when upstream stages fail.

Important

  • Prefer reusable workflows/templates/actions to copy-pasted job definitions.
  • Prefer a small number of clear stages over large DAGs with many conditional branches.
  • Keep the same core commands usable locally and in CI.
  • Use one repository-level convention for artifact paths, working directories, and cache locations.
  • Pin actions/tasks to a reviewed major version or commit according to team risk tolerance.

DHI good practice

  • Keep YAML files shallow enough that a new team member can follow the main path in a few minutes.
  • Put long comments in nearby documentation rather than inside the pipeline file itself.
  • Create shared pipeline building blocks for repeated patterns such as .NET restore/build/test, container publishing, or deployment promotion.

Keep complexity out of the pipeline

Prefer this split of responsibilities:

  • Pipeline YAML: triggers, permissions, job order, artifact flow, environment promotion.
  • Repository scripts/tools: application-specific commands, packaging details, validation rules, release notes generation.
  • Infrastructure as Code: provisioning and environment definition.

Avoid building large one-off shell scripts directly inside YAML when the same logic could live in a reviewed script file.

  1. Validate or lint pipeline inputs
  2. Restore dependencies
  3. Build
  4. Test
  5. Package artifacts
  6. Publish artifacts
  7. Deploy to non-production environment
  8. Run smoke or integration checks
  9. Promote to production with the required approval model

Not every repository needs every stage, but this shape makes intent easy to follow.

Desktop and installer pipelines

Desktop delivery often adds packaging and signing steps that should remain explicit:

  • Build binaries
  • Package installer or ZIP deliverable
  • Sign binaries or installers where required
  • Publish installer artifacts with checksums and release notes
  • Run install, launch, upgrade, or uninstall smoke tests where practical

Keep signing and publishing separate from compile steps so access to sensitive credentials stays limited.

Review checklist

  • Is the pipeline easy to explain end-to-end?
  • Are application-specific details abstracted into repository scripts or tools?
  • Are secrets referenced securely rather than embedded?
  • Are artifact names, versions, and publish paths consistent?
  • Is rollback or redeploy possible from an existing artifact?
  • Are environment approvals and deployment boundaries clear?
  • Is IaC handled in a clear companion workflow when infrastructure changes are required?