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).
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.
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.
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).
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: