1.. _docs-github: 2 3=========== 4GitHub 5=========== 6 7Overview 8======== 9 10Pigweed itself uses `LUCI <luci>`_ for 11:abbr:`CI/CD (Continuous Integration/Continuous Deployment)`. LUCI is 12well-supported within Google but complicated to deploy, so Pigweed has support 13for `GitHub Actions <github-actions>`_ as well. 14 15.. _github-actions: https://docs.github.com/en/actions 16 17Bazel 18===== 19Configuring a Bazel builder that runs on pull requests is straightforward. 20There are four steps: `checkout`_, `get Bazel`_, build, and test. There 21are good community-managed actions for the first two steps, and the last two 22steps are trivial (and can even be combined). 23 24.. _checkout: https://github.com/marketplace/actions/checkout 25.. _get Bazel: https://github.com/marketplace/actions/setup-bazel-environment 26 27The Bazel version retrieved is configured through a ``.bazelversion`` file in 28the root of the checkout. 29 30.. code-block:: yaml 31 32 name: basic 33 run-name: presubmit run triggered by ${{ github.actor }} 34 35 on: 36 pull_request: 37 types: [opened, synchronize, reopened] 38 39 jobs: 40 bazel-build-test: 41 runs-on: ubuntu-latest 42 steps: 43 - name: Checkout 44 uses: actions/checkout@v4 45 with: 46 fetch-depth: 0 47 submodules: recursive 48 - name: Get Bazel 49 uses: bazel-contrib/setup-bazel@0.8.1 50 with: 51 # Avoid downloading Bazel every time. 52 bazelisk-cache: true 53 # Store build cache per workflow. 54 disk-cache: ${{ github.workflow }} 55 # Share repository cache between workflows. 56 repository-cache: true 57 - name: Bazel Build 58 run: bazel build ... 59 - name: Bazel Test 60 run: bazel test ... 61 62``pw presubmit`` 63================ 64Configuring a builder that uses `pw_env_setup <module-pw_env_setup>`_ and 65`pw_presubmit <module-pw_presubmit>`_ is also relatively simple. When run 66locally, ``bootstrap.sh`` has several checks to ensure it's "sourced" instead of 67directly executed. A `trivial wrapper script` is included in ``pw_env_setup`` 68that gets around this. 69 70.. _trivial wrapper script: https://cs.opensource.google/pigweed/pigweed/+/main:pw_env_setup/run.sh 71 72When ``pw_env_setup`` is run within a GitHub Action, it recognizes this from the 73environment and writes the environment variables in a way 74`understood by GitHub`_, and GitHub makes those variables available to 75subsequent steps. 76 77.. _understood by GitHub: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable 78 79For Pigweed itself, the only ``pw_presubmit``-based action runs lintformat. To 80test all of Pigweed requires more resources than the free GitHub runners 81provide, but small projects using just part of Pigweed may be more successful. 82 83.. code-block:: yaml 84 85 name: lintformat 86 87 on: 88 pull_request: 89 types: [opened, synchronize, reopened] 90 91 jobs: 92 bazel-build-test: 93 runs-on: ubuntu-latest 94 steps: 95 - name: Checkout 96 uses: actions/checkout@v4 97 with: 98 fetch-depth: 0 99 submodules: recursive 100 - name: Bootstrap 101 run: pw_env_setup/run.sh bootstrap.sh 102 - name: python_format 103 run: pw presubmit --program lintformat --keep-going 104 105Note that Pigweed does not accept pull requests on GitHub, so we do not define 106GitHub actions that trigger from pull requests. Instead, we trigger on pushes to 107GitHub. 108