CI Tools Pipeline

CI Tools Pipeline Skill

Use this skill to build proper GitLab CI/CD pipelines from the CI Tools Components Catalog. Prefer catalog components over custom jobs when a component exists for the job type.

Quick Start

1. Read the project AGENTS.md first, then inspect the repository layout, current .gitlab-ci.yml, and existing pipeline failures.
2. Open the live catalog before choosing components:
   • Catalog: https://ci-tools.xrow.de/
   • Components index: https://ci-tools.xrow.de/Components/
   • Source: https://gitlab.com/xrow-public/ci-tools
3. Select the smallest component set that covers the project:
   • Baseline: common, workflow, semantic-release
   • Hygiene: label, pre-commit, spellcheck, trivy
   • Languages and test runners: bash-unit-tests, lint-javascript, lint-json, lint-yaml, lint-markdown, lint-ansible, lint-helm, lint-tofu
   • Build and package: container, buildah, helm, helm-docs, package, package-skill, oras-push
   • Docs and sites: docusaurus, publish-sitemap, publish-wiki
   • Delivery: deploy-helm, deploy-argocd, gitops, app-of-apps
   • Project flow: workflow-trunkbased, workflow-gitflow
4. Validate locally before pushing:
   • glab ci lint .gitlab-ci.yml
   • Lint any included template files when supported by the project.
   • Run the narrowest local test for scripts or generated configuration.

Pipeline Design

• Keep root pipelines component-driven. Add handwritten jobs only when no component exists or a project-specific integration is unavoidable.
• Use $CI_SERVER_FQDN/xrow-public/ci-tools/@main for component includes when package registry or fully-qualified host behavior matters; otherwise match the existing project style.
• Put component inputs next to the include and keep names stable across related jobs.
• Prefer continuous delivery defaults. Do not create automatic production deployment unless the project already does that or the issue explicitly asks for it.
• Keep validation jobs independent of deployment jobs so a project can fail fast before writing to registries, clusters, or external systems.
• Use needs and dependencies only when a real artifact or ordering relationship exists.
• Never use allow_failure: true, when: manual, rules: when: never, or skipped tests to hide a broken required pipeline. Use them only when the job is genuinely optional, documented, or intentionally gated.

Component Selection Heuristics

Repository Bootstrap

Use these components for most repositories:

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/common@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/label@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/pre-commit@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/trivy@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/workflow@main
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/semantic-release@main

Use label early when the project needs standard priority::*, size::*, type::*, and workflow::* labels for automation.

Containers

Use container for normal application images and buildah when the project needs direct image build control. Set name and path explicitly when the repository has multiple build roots.

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/container@main
    inputs:
      name: app
      path: container/app

Helm Charts

Use helm for chart build/test/publish flows and add helm-docs when chart documentation must be generated. Set test-enabled: false only when there is no safe cluster-backed test path.

include:
  - component: $CI_SERVER_HOST/xrow-public/ci-tools/helm@main
    inputs:
      name: chart
      path: chart

Review Testing

Keep review environments close to production while making destructive checks explicit and temporary. For Helm review tests, validate install, upgrade, readiness, ingress, cleanup, and storage behavior through chart values instead of ad hoc shell overrides. Document any review-only threshold or fixture in the MR so reviewers can see why it differs from production defaults.

Documentation

Use docusaurus for docs sites and pair it with publish-sitemap when the project publishes public pages. Pass name and path explicitly.

Infrastructure and GitOps

Use lint-ansible, ansible-collection, ansible-ee, ansible-runner, lint-tofu, tofu-module, gitops, deploy-argocd, and app-of-apps according to the repository type. Keep plan, build, and deploy stages separate unless the catalog component documents a tighter flow.

Validation Workflow

1. Fetch the live component page and verify the input names before editing:

   curl -fsSL https://ci-tools.xrow.de/Components/ | sed -n '1,220p'
   

2. Lint the pipeline:

   glab ci lint .gitlab-ci.yml
   

3. For merge requests, push with CI skipped first, then start an MR pipeline through GitLab Agent rules:

   git push origin  -o ci.skip
   glab ci run --mr
   

4. If CI fails, inspect the failed job trace and fix the underlying problem. If the failure comes from the catalog or main branch, open or link the dependency and mark the MR blocked rather than weakening the pipeline.

Review Checklist

• The pipeline uses CI Tools components where available.
• Component inputs match the live catalog documentation.
• Protected branch behavior is respected.
• Required checks are not hidden behind skips or allow_failure.
• Registry, cluster, and deploy writes are gated by existing project rules.
• The MR description lists the plan, acceptance criteria, and validation commands.