Skip to content

Pin and upgrade a component

Add a component for the first time

Every component is included by URL, pinned to an exact tag:

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]

Never pin @~latest or a branch — see Reference for the component you need and its full inputs table. Most components need at least stage to fit your pipeline's stages: list; some (tofu-plan, svelte-build, svelte-lint, svelte-security, svelte-test, tofu-module-publish) have one or more required inputs with no default — check the component's Reference page before including it.

Let Renovate keep the pin current

Rather than upgrading by hand, extend the bundled preset in your renovate.json / renovate.json5:

{ "extends": ["gitlab>phpboyscout/cicd"] }

This adds a custom manager that tracks every gitlab.com/phpboyscout/cicd/<name>@vX.Y.Z pin in your .gitlab-ci.yml and opens an MR whenever a new cicd release ships. Pair it with the renovate-self component if you don't already run Renovate on a schedule.

Reviewing a Renovate MR

When a Renovate MR bumps a phpboyscout/cicd pin:

  1. Check the version span, pre-1.0. While the major version is 0, a minor bump (v0.17.0 → v0.18.0) may change a component's input shape — a new input, a changed default, occasionally a renamed one. A patch bump (v0.18.0 → v0.18.1) never does.
  2. Read the component's entry in the decision log for that version. Every input-shape change is a spec; the decision log links straight to it. For a multi-version jump (several minors at once), check every entry in the range, not just the newest.
  3. Diff the input keys, not just the version number, if you're upgrading by hand across several minors: list the inputs your .gitlab-ci.yml sets, and check each still exists with the meaning you expect. An added input with a sensible default is always safe to ignore. A removed or renamed input needs a corresponding edit on your side.
  4. Let the pipeline be the final check. The MR's own pipeline runs the component against your real project — a removed/renamed input you missed will fail loudly (an unknown-input or missing-required-input error at pipeline-creation time), not silently.

Upgrading across many versions at once

If a pin has drifted many minors behind, it's tempting to assume the jump is risky in proportion to how large the version gap looks. It usually isn't — the risk lives in the interface, not the version number. Read every relevant spec in the decision log for the span you're crossing, and categorise each change: additive (new input, stable default) is safe regardless of how many of those you cross; any removal, rename, or newly-required input needs an explicit fix on your side, no matter how small the version delta looks.

See also