Add clear comments explaining the rationale behind configuration decisions, especially for workarounds, compatibility fixes, or environment-specific settings. This helps future maintainers understand why certain configurations exist and prevents accidental removal of necessary settings during refactoring.
Good examples:
# back compat for pre-unified-/usr distros, do not add new OSes
- remote: sudo ln -s /usr/bin/install /bin/install
# We have to use 20.04 host for these operations otherwise
# the dokken images throw timedatectl error
linux-2004-host:
Prefer specific version identifiers over relative terms (like “latest”) to ensure reproducibility and prevent unexpected behavior when defaults change:
# Instead of: name: macos-latest # arm64
- name: macos-14 # arm64
Enter the URL of a public GitHub repository