1.. _docs-github-actions: 2 3=========================================== 4Set up GitHub Actions for a Pigweed project 5=========================================== 6.. _GitHub Actions: https://docs.github.com/en/actions 7 8This tutorial shows you how to set up `GitHub Actions`_ to build and test your 9Bazel-based Pigweed project. You'll learn how to set up both presubmit and 10postsubmit Actions. 11 12.. _docs-github-actions-examples: 13 14-------- 15Examples 16-------- 17Pigweed's :ref:`Bazel quickstart repo <docs-get-started-bazel>` demonstrates 18GitHub Actions integration: 19 20* `//.github/workflows/presubmit.yaml <https://pigweed.googlesource.com/pigweed/quickstart/bazel/+/refs/heads/main/.github/workflows/presubmit.yaml>`_ 21* `//.github/workflows/postsubmit.yaml <https://pigweed.googlesource.com/pigweed/quickstart/bazel/+/refs/heads/main/.github/workflows/postsubmit.yaml>`_ 22 23.. _docs-github-actions-enable: 24 25-------------- 26Enable Actions 27-------------- 28.. _Managing GitHub Actions settings for a repository: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository 29 30Make sure that Actions are enabled for your repo. See 31`Managing GitHub Actions settings for a repository`_. 32 33----------------------------------------- 34Create a .bazelversion file for your repo 35----------------------------------------- 36.. _.bazelversion: https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#how-does-bazelisk-know-which-bazel-version-to-run 37 38Make sure that `.bazelversion`_ exists in your repo. This file specifies what 39version of Bazel the Actions should use. 40 41.. _docs-github-actions-presubmit: 42 43------------------------- 44Create a presubmit Action 45------------------------- 46A presubmit Action runs when a pull request is sent. Creating a presubmit 47Action that makes sure pull requests build and pass tests involves four steps: 48 49#. Checking out your repo's code. 50 51#. Installing Bazel. 52 53#. Building your code. 54 55#. Testing your code. 56 57The first two steps are handled by community-managed extensions. The last 58two steps require just a few lines of code. 59 60#. From the root of your repository, create ``.github/workflows/presubmit.yaml``. 61 The path to the file must be ``.github/workflows`` but you can name the file 62 whatever you want. 63 64#. Put the following YAML into the file: 65 66 .. code-block:: yaml 67 68 name: presubmit 69 run-name: presubmit run triggered by ${{ github.actor }} 70 71 on: 72 pull_request: 73 types: [opened, synchronize, reopened] 74 75 jobs: 76 bazel-build-test: 77 runs-on: ubuntu-latest 78 steps: 79 - name: Checkout 80 # Check out this repo's code. 81 # https://github.com/actions/checkout 82 uses: actions/checkout@v4 83 with: 84 fetch-depth: 0 85 submodules: recursive 86 - name: Get Bazel 87 # Install Bazel. 88 # https://github.com/bazel-contrib/setup-bazel 89 uses: bazel-contrib/setup-bazel@0.8.1 90 with: 91 # Avoid downloading Bazel every time. 92 bazelisk-cache: true 93 # Store build cache per workflow. 94 disk-cache: ${{ github.workflow }} 95 # Share repository cache between workflows. 96 repository-cache: true 97 - name: Bazel Build 98 # Always use bazelisk rather than bazel to 99 # guarantee that the correct version of Bazel 100 # (sourced from .bazelversion) is used. 101 run: bazelisk build ... 102 - name: Bazel Test 103 run: bazelisk test ... 104 105#. Commit the file. 106 107The Action runs whenever a pull request is opened, updated, or 108reopened. 109 110.. _Bazelisk: https://bazel.build/install/bazelisk 111 112.. note:: 113 114 In general, Pigweed recommends always launching Bazel through 115 the ``bazelisk`` command rather than the ``bazel`` command. 116 `Bazelisk`_ guarantees that you're always running the correct 117 version of Bazel for your project, as defined in your project's 118 ``.bazelversion`` file. It would technically be OK to use the 119 ``bazel`` command in your GitHub Actions code because the 120 ``bazel-contrib/setup-bazel`` extension also makes sure to launch 121 the correct version of Bazel based on what's defined in ``.bazelversion``, 122 but in practice Pigweed finds it safer to just use ``bazelisk`` everywhere. 123 124.. _docs-github-actions-postsubmit: 125 126-------------------------- 127Create a postsubmit Action 128-------------------------- 129A postsubmit Action runs after a pull request has been merged. 130The process for creating a postsubmit Action that builds and tests your code 131when a new commit is pushed is almost identical to 132:ref:`the presubmit Action setup <docs-github-actions-presubmit>`. The 133only thing that changes is the ``on`` field in the YAML: 134 135.. code-block:: yaml 136 137 name: postsubmit 138 run-name: postsubmit run 139 140 on: 141 push 142 143 jobs: 144 bazel-build-test: 145 runs-on: ubuntu-latest 146 steps: 147 - name: Checkout 148 # Check out this repo's code. 149 # https://github.com/actions/checkout 150 uses: actions/checkout@v4 151 with: 152 fetch-depth: 0 153 submodules: recursive 154 - name: Get Bazel 155 # Install Bazel. 156 # https://github.com/bazel-contrib/setup-bazel 157 uses: bazel-contrib/setup-bazel@0.8.1 158 with: 159 # Avoid downloading Bazel every time. 160 bazelisk-cache: true 161 # Store build cache per workflow. 162 disk-cache: ${{ github.workflow }} 163 # Share repository cache between workflows. 164 repository-cache: true 165 - name: Bazel Build 166 # Always use bazelisk rather than bazel to 167 # guarantee that the correct version of Bazel 168 # (sourced from .bazelversion) is used. 169 run: bazelisk build ... 170 - name: Bazel Test 171 run: bazelisk test ... 172 173.. _docs-github-actions-linter: 174 175-------------------------------------------------------------- 176Create a linter Action that uses pw_presubmit and pw_env_setup 177-------------------------------------------------------------- 178The following code demonstrates a presubmit linter Action that uses 179:ref:`module-pw_env_setup` and :ref:`module-pw_presubmit`. 180 181.. code-block:: yaml 182 183 name: lintformat 184 185 on: 186 pull_request: 187 types: [opened, synchronize, reopened] 188 189 jobs: 190 bazel-build-test: 191 runs-on: ubuntu-latest 192 steps: 193 - name: Checkout 194 uses: actions/checkout@v4 195 with: 196 fetch-depth: 0 197 submodules: recursive 198 - name: Bootstrap 199 # When run locally, bootstrap.sh has checks to ensure that 200 # it's sourced (source bootstrap.sh) rather than executed 201 # directly. run.sh gets around this. 202 run: pw_env_setup/run.sh bootstrap.sh 203 - name: lintformat 204 run: pw presubmit --program lintformat --keep-going 205 206.. _understood by GitHub: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable 207 208When ``pw_env_setup`` is run within a GitHub Action, it recognizes this from 209the environment and writes the environment variables in a way that is 210`understood by GitHub`_, and GitHub makes those variables available to 211subsequent steps. 212 213------------------- 214Create more Actions 215------------------- 216.. _official GitHub Actions docs: https://docs.github.com/en/actions 217 218You can create as many Actions as you want! Just add new files to 219``//.github/workflows`` and tweak the options as needed. Check out 220the `official GitHub Actions docs`_ to learn more. 221 222.. _docs-github-actions-support: 223 224------- 225Support 226------- 227Please start a discussion in Pigweed's `Discord <https://discord.gg/M9NSeTA>`_. 228