.. _docs-github-actions:

===========================================
Set up GitHub Actions for a Pigweed project
===========================================
.. _GitHub Actions: https://docs.github.com/en/actions

This tutorial shows you how to set up `GitHub Actions`_ to build and test your
Bazel-based Pigweed project. You'll learn how to set up both presubmit and
postsubmit Actions.

.. _docs-github-actions-examples:

--------
Examples
--------
Pigweed's :ref:`Bazel quickstart repo <docs-get-started-bazel>` demonstrates
GitHub Actions integration:

* `//.github/workflows/presubmit.yaml <https://pigweed.googlesource.com/pigweed/quickstart/bazel/+/refs/heads/main/.github/workflows/presubmit.yaml>`_
* `//.github/workflows/postsubmit.yaml <https://pigweed.googlesource.com/pigweed/quickstart/bazel/+/refs/heads/main/.github/workflows/postsubmit.yaml>`_

.. _docs-github-actions-enable:

--------------
Enable Actions
--------------
.. _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

Make sure that Actions are enabled for your repo. See
`Managing GitHub Actions settings for a repository`_.

-----------------------------------------
Create a .bazelversion file for your repo
-----------------------------------------
.. _.bazelversion: https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#how-does-bazelisk-know-which-bazel-version-to-run

Make sure that `.bazelversion`_ exists in your repo. This file specifies what
version of Bazel the Actions should use.

.. _docs-github-actions-presubmit:

-------------------------
Create a presubmit Action
-------------------------
A presubmit Action runs when a pull request is sent. Creating a presubmit
Action that makes sure pull requests build and pass tests involves four steps:

#. Checking out your repo's code.

#. Installing Bazel.

#. Building your code.

#. Testing your code.

The first two steps are handled by community-managed extensions. The last
two steps require just a few lines of code.

#. From the root of your repository, create ``.github/workflows/presubmit.yaml``.
   The path to the file must be ``.github/workflows`` but you can name the file
   whatever you want.

#. Put the following YAML into the file:

   .. code-block:: yaml

      name: presubmit
      run-name: presubmit run triggered by ${{ github.actor }}

      on:
        pull_request:
          types: [opened, synchronize, reopened]

      jobs:
        bazel-build-test:
          runs-on: ubuntu-latest
          steps:
            - name: Checkout
              # Check out this repo's code.
              # https://github.com/actions/checkout
              uses: actions/checkout@v4
              with:
                fetch-depth: 0
                submodules: recursive
            - name: Get Bazel
              # Install Bazel.
              # https://github.com/bazel-contrib/setup-bazel
              uses: bazel-contrib/setup-bazel@0.8.1
              with:
                # Avoid downloading Bazel every time.
                bazelisk-cache: true
                # Store build cache per workflow.
                disk-cache: ${{ github.workflow }}
                # Share repository cache between workflows.
                repository-cache: true
            - name: Bazel Build
              # Always use bazelisk rather than bazel to
              # guarantee that the correct version of Bazel
              # (sourced from .bazelversion) is used.
              run: bazelisk build ...
            - name: Bazel Test
              run: bazelisk test ...

#. Commit the file.

The Action runs whenever a pull request is opened, updated, or
reopened.

.. _Bazelisk: https://bazel.build/install/bazelisk

.. note::

   In general, Pigweed recommends always launching Bazel through
   the ``bazelisk`` command rather than the ``bazel`` command.
   `Bazelisk`_ guarantees that you're always running the correct
   version of Bazel for your project, as defined in your project's
   ``.bazelversion`` file. It would technically be OK to use the
   ``bazel`` command in your GitHub Actions code because the
   ``bazel-contrib/setup-bazel`` extension also makes sure to launch
   the correct version of Bazel based on what's defined in ``.bazelversion``,
   but in practice Pigweed finds it safer to just use ``bazelisk`` everywhere.

.. _docs-github-actions-postsubmit:

--------------------------
Create a postsubmit Action
--------------------------
A postsubmit Action runs after a pull request has been merged.
The process for creating a postsubmit Action that builds and tests your code
when a new commit is pushed is almost identical to
:ref:`the presubmit Action setup <docs-github-actions-presubmit>`. The
only thing that changes is the ``on`` field in the YAML:

.. code-block:: yaml

   name: postsubmit
   run-name: postsubmit run

   on:
     push

   jobs:
     bazel-build-test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           # Check out this repo's code.
           # https://github.com/actions/checkout
           uses: actions/checkout@v4
           with:
             fetch-depth: 0
             submodules: recursive
         - name: Get Bazel
           # Install Bazel.
           # https://github.com/bazel-contrib/setup-bazel
           uses: bazel-contrib/setup-bazel@0.8.1
           with:
             # Avoid downloading Bazel every time.
             bazelisk-cache: true
             # Store build cache per workflow.
             disk-cache: ${{ github.workflow }}
             # Share repository cache between workflows.
             repository-cache: true
         - name: Bazel Build
           # Always use bazelisk rather than bazel to
           # guarantee that the correct version of Bazel
           # (sourced from .bazelversion) is used.
           run: bazelisk build ...
         - name: Bazel Test
           run: bazelisk test ...

.. _docs-github-actions-linter:

--------------------------------------------------------------
Create a linter Action that uses pw_presubmit and pw_env_setup
--------------------------------------------------------------
The following code demonstrates a presubmit linter Action that uses
:ref:`module-pw_env_setup` and :ref:`module-pw_presubmit`.

.. code-block:: yaml

   name: lintformat

   on:
     pull_request:
       types: [opened, synchronize, reopened]

   jobs:
     bazel-build-test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
           with:
             fetch-depth: 0
             submodules: recursive
         - name: Bootstrap
           # When run locally, bootstrap.sh has checks to ensure that
           # it's sourced (source bootstrap.sh) rather than executed
           # directly. run.sh gets around this.
           run: pw_env_setup/run.sh bootstrap.sh
         - name: lintformat
           run: pw presubmit --program lintformat --keep-going

.. _understood by GitHub: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable

When ``pw_env_setup`` is run within a GitHub Action, it recognizes this from
the environment and writes the environment variables in a way that is
`understood by GitHub`_, and GitHub makes those variables available to
subsequent steps.

-------------------
Create more Actions
-------------------
.. _official GitHub Actions docs: https://docs.github.com/en/actions

You can create as many Actions as you want! Just add new files to
``//.github/workflows`` and tweak the options as needed. Check out
the `official GitHub Actions docs`_ to learn more.

.. _docs-github-actions-support:

-------
Support
-------
Please start a discussion in Pigweed's `Discord <https://discord.gg/M9NSeTA>`_.