Prerequisites

What You'll Learn

What if I get stuck?

If you get stuck with GitHub Actions, check out the official documentation.

You can find usage examples of the setup-please action in this repository.

If you really get stuck you can find us on gitter!

GitHub Actions is an extensible CI/CD platform provided by GitHub. Compared to other CI/CD solutions, GitHub Actions allows you to build all kinds automations (called workflows) triggered by various events (eg. pushing code to a branch).

Setting up GitHub Actions

Workflow definitions are simple YAML files stored in the .github/workflows directory of your repository.

The following snippet triggers a workflow named CI whenever commits are pushed to the master branch:

name: CI

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Test
        run: echo "Tests passed"

Go ahead and add the above snippet to .github/workflows/ci.yaml in your project. Then go to https://github.com/YOU/YOUR-PROJECT/actions and observe the workflow.

Now we have a project setup with GitHub Actions, it's time to start building with Please! Let's change ci.yaml a little:

name: CI

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest

    steps:
      # Setup your language of choice here:
      # https://github.com/actions/?q=setup-&type=&language=

      - name: Checkout code
        uses: actions/checkout@v2

      # Run please build
      - name: Test
        run: ./pleasew build //...

Compared to the example earlier, this workflow uses the pleasew script to download Please and build the project.

Notice the //... bit at the end of the command: it's necessary on GitHub Actions. Check this issue for more details.

The setup-please action provides better integration for Please.

What is an action?

As you've seen in the previous examples, workflows consist of steps. A workflow step can be as simple as a shell script:

- name: Test
  run: ./pleasew build //...

Shell scripts (no matter how awesome they are) are not always the right tool for the job. Complex build steps might require a more expressive language which takes us to the second type of workflow steps, called actions:

- name: Checkout code
  uses: actions/checkout@v2

An action can be written in any language (distributed as Docker images), but JavaScript is supported natively.

Why not just use ./pleasew?

The above section about actions begs the question: why not just use pleasew? Why do we need an action for running Please.

Please itself can perfectly run on GitHub Actions on its own, so you don't need an action per se. That being said, there are a couple issues when using pleasew:

The setup-please action provides better integration for Please solving the above issues (and a lot more).

Using the setup-please action

Adding the setup-please action to your workflow is simply adding two lines:

name: CI

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest

    steps:
      # Setup your language of choice here:
      # https://github.com/actions/?q=setup-&type=&language=

      - name: Checkout code
        uses: actions/checkout@v2

      # Make sure it's added after the checkout step
      - name: Set up Please
        uses: sagikazarmark/setup-please-action@v0

      # Run please build
      # You can use plz thanks to the setup action
      - name: Test
        run: plz test //...

The readme of setup-please explains more use cases and configuration options: