156 lines · plain
1======================2LLVM CI Best Practices3======================4 5Overview6========7 8This document contains a list of guidelines and best practices to use when9working on LLVM's CI systems. These are intended to keep our actions reliable,10consistent, and secure.11 12GitHub Actions Best Practices13=============================14 15This section contains information on best practices/guidelines when working on16LLVM's GitHub actions workflows.17 18Disabling Jobs In Forks19-----------------------20 21There are many LLVM forks that exist, and we currently default to preventing22actions from running outside of the LLVM organization to prevent them from23running in forks. We default to this as actions running in forks are usually24not desired and only run by accident. In addition, many of our workflows25assume that they are operating within the main LLVM repository and break26otherwise.27 28Adhering to this best practice looks like adding the following to each of the29jobs specified within a workflow:30 31.. code-block:: yaml32 33 jobs:34 <job name>:35 if: github.repository_owner == 'llvm'36 37We choose to use ``github.repository_owner`` rather than ``github.repository``38to enable these workflows to run in forks inside the LLVM organization, such as39the ClangIR fork.40 41There are some exceptions to this rule where ``github.repository`` might be42used when it makes sense to limit a workflow to only running in the main43monorepo repository. These include things like the issue subscriber and44release tasks, which should not run anywhere else.45 46Hash Pinning Dependencies47-------------------------48 49GitHub Actions allows the use of actions from other repositories as steps in50jobs. We take advantage of various actions for a variety of different tasks,51but especially tasks like checking out the repository, and52downloading/uploading build caches. These actions are typically versioned with53just a release, which looks like the following:54 55.. code-block:: yaml56 57 steps:58 - name: Checkout LLVM59 uses: actions/checkout@v460 61However, it is best practice to specify an exact commit SHA from which to pull62the action, noting the version in a comment:63 64We plan on revisiting this recommendation once GitHub's immutable actions have65been rolled out as GA.66 67.. code-block:: yaml68 69 steps:70 - name: Checkout LLVM71 uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.272 73This is beneficial for two reasons: reliability and security. Specifying an74exact SHA rather than just a major version ensures we end up running the same75action originally specified when the workflow was authored and/or updated,76and that no breaking changes sneak in from new versions of a workflow being77released. However, this effect could also be achieved by specifying an exact78dot release. The biggest reason to prefer hash pinned dependencies is security.79Release assets on GitHub are mutable, allowing an attacker to change the code80within a specific version of an action after the fact, potentially stealing81sensitive tokens and credentials. Hash pinning the dependencies prevents this82as the hash would change with the code.83 84Using Versioned Runner Images85-----------------------------86 87GitHub actions allows the use of either specifically versioned runner images88(e.g., ``ubuntu-22.04``), or just the latest runner image89(e.g., ``ubuntu-latest``). It is best practice to use explicitly versioned90runner images. This prevents breakages when GitHub rolls the latest runner91image to a new version with potentially breaking changes, instead allowing us92to explicitly opt-in to using the new image when we have done sufficient93testing to ensure that our existing workflows work as expected in the new94environment.95 96Top Level Read Permissions97--------------------------98 99The top of every workflow should specify that the job only has read100permissions:101 102.. code-block:: yaml103 104 permissions:105 contents: read106 107If specific jobs within the workflow need additional permissions, those108permissions should be added within the specific job. This practice locks down109all permissions by default and only enables them when needed, better enforcing110the principle of least privilege.111 112Ensuring Workflows Run on the Correct Events113--------------------------------------------114 115GitHub allows workflows to run on a multitude of events, and it is important to116configure a workflow such that it triggers on the correct events. There are117two main best practices around events that trigger workflows:118 1191. Workflows that are designed to run on pull requests should not be120restricted by target branch. Restricting the target branch unnecessarily121will prevent any stacked PRs from being tested. ``pull_request`` events should122not contain a branches key.123 1242. Workflows that are designed to also trigger on push events (e.g., for125testing on ``main`` or one of the release branches) need to be restricted by126branch. While pushes to a fork will not trigger a workflow run due to the127``push`` event if the workflow already has its jobs disabled in forks128(described above), stacked PRs will end up running jobs twice if the ``push``129event does not have any branch restrictions. ``push`` events should have130their branches restricted at the very least to ``main`` and the release131branches as follows:132 133.. code-block:: yaml134 135 push:136 branches:137 - main138 - release/*139 140Container Best Practices141========================142 143This section contains best practices/guidelines when working with containers144for LLVM infrastructure.145 146Using Fully Qualified Container Names147-------------------------------------148 149When referencing container images from a registry, such as in GitHub Actions150workflows, or in ``Dockerfile`` files used for building images, prefer fully151qualified names (i.e., including the registry domain) over just the image.152For example, prefer ``docker.io/ubuntu:24.04`` over ``ubuntu:24.04``. This153ensures portability across systems where a different default registry might154be specified and also prevents attackers from changing the default registry155to pull in a malicious image instead of the intended one.156