Rationale

You want to keep your project healthy, approachable, and maintain readable CI/CD pipelines. You want to avoid strong dependencies on specific vendors, technologies, or CI runners, ensuring the flexibility to switch providers if needed.

Vendor lock-in is problematic, among other reasons, because:

  • Cost model can change
  • Feature sets, and the api surface to access it may change and go in a direction you don’t like
  • Changes in ToS
  • Competitors may get better and should be re-considered, or new options can be evaluated

How

With a few simple precautions and sustained attention, you can achieve this:

  1. Where possible, implement CI/CD steps in a “native” way (i.e. commands runnable by any shell), with your platform CI/CD (e.g. GitHub Actions, GitLab pipelines, etc) functioning solely as an executor.

    Example

    The docker-build.yaml file in isso-comments/isso shows GitHub Action-specific “jargon” and heavy reliance on external actions. In contrast, rgbds build-container.yml accomplishes similar tasks minimizes reliance on GitHub-specific actions, prioritizing native scripting/commands.

  2. Don’t rely on platform-specific features in the YAML, unless strictly necessary (e.g. for triggers). When doing so, comment and document appropriately.

  3. Limit manual steps. If a manual step is involved, please document it directly in the pipelines or in a separate “CICD.md” document.

  4. All scripts should be runnable locally with minimal changes, allowing contributors to reproduce, debug, and test workflows outside the CI environment. If possible, comment directly on the YAML suggesting how platform-specific steps can be run locally.

  5. Limit the use of external actions and templating/abstractions within your workflows. Prefer straightforward scripts or commands instead of relying on complex or external platform-specific actions maintained by third parties.

  6. Don’t be scared of over-documenting. Setting up a CI/CD, even if it already exists can be a daunting task and something can always be missed somewhere. It also cannot be fully-automated because of the moving (and not exposed) surfaces of the vendors/platforms. Document.

  7. Every once in a while (set up a policy for this), try to see how easy would it be to re-set up everything from the ground up and how much would it cost. Is there something you wouldn’t know how to do? Or only some person would know? Document.

  8. Pay attention to the steps and assets that are not (and cannot be) part of the git repository itself. This includes flags and settings in the CI platform, tokens (how do you generate AND set them), repository secrets, ssh keys to perform git operations in the pipelines, etc. If your platform exposes an endpoint to export, in a serialized version, the entire repository settings, perform that regularly (even if the same file cannot be “repushed” into the platform to re-create the repository, it’s a good reference). Document.

  9. Do not use CI/CD pipelines for things that should go somewhere else (…).