In this series of publications I will briefly explain what it is and how to integrate GitHub Actions with different technologies, such as Android, iOS or a web application.
What is GitHub Actions
It is a feature offered by GitHub that allows developers to create workflows that can be used to compile, test and deploy code, giving the possibility of creating CI/CD flows within the git repository.
Workflows must contain at least one job. These include a series of steps that perform individual tasks that can be actions or commands. A workflow can start with different events(triggers) that happen within GitHub, such as push to the repository or the creation of a pull request.
In this tutorial I will create a workflow to execute unit tests of an Android project so the success result can be used as status check of a pull request. With this configuration the pull request must pass the unit tests before other members of a team can do code review.
You can see the workflow running in this demo repository
- Simple android project on GitHub
Create workflow file
Workflow files must be stored in the folder
yaml format in the root repository.
Create the file
.github/workflows/android-feature.yml with the following content:
name: Android Feature Branch CI on: push: branches: - '*' - '!master' jobs: test: name: Run Unit Tests runs-on: ubuntu-18.04 steps: - uses: actions/checkout@v1 - name: Set up JDK 1.8 uses: actions/setup-java@v1 with: java-version: 1.8 - name: Unit tests run: bash ./gradlew test --stacktrace
Understanding the workflow
name: Android Feature Branch CI
The firts part is the name of the workflow.
on: push: branches: - '*' - '!master'
In this section, we can define over which branch and event this workflow will be executed. For this example, the workflow will be executed on any branch different of master for push event.
jobs: test: name: Run Unit Tests runs-on: ubuntu-18.04
We can define any number of jobs in a workflow, for now we are just creating one called
test. We need to specify a name and over which type of virtual machine will run, in this case we will use
ubuntu-18.04. Available virtual machines can be found here.
Finally, I have defined steps that are included in a job. They are tasks that are executed in sequence in the same virtual machine.
steps: - uses: actions/checkout@v1 - name: Set up JDK 1.8 uses: actions/setup-java@v1 with: java-version: 1.8 - name: Unit tests run: bash ./gradlew test --stacktrace
test job I have three steps, each one created a little bit differently. First one,
— uses: actions/checkout@1 , is an action. It is a reusable unit which is provided by GitHub, you or other public repository. More about it you can found in official documentation.
The goal of the first action is to allow a workflow to access the content of the repository.
Second step is more complex, but have simple goal, set up a JDK version to be Java 8.
- name: Set up JDK 1.8 uses: actions/setup-java@v1 with: java-version: 1.8
Finally, a third step runs unit tests located in the project. As it is an Android project, it uses Gradle for build lifecycle, therefore to run the test we need to use Gradle Wrapper file. The command is the same as you would do it in the terminal on your computer.
- name: Unit tests run: bash ./gradlew test --stacktrace
We are done in order to try this, we just need to create a branch and push the changes to the repository. After that, go to
Actions tab in the project to check wether the workflow has been triggered.
After more than a minute, the workflow successfully finished. 🚀
GitHub status checks
In order to make this workflow to be a status check in your GitHub repository, a simple branch protection rule is needed for master. Just go to
Settings -> Branches -> Add rule and create the following rule selecting the name of the job to be used, in this case our job name is
Run Unit Tests. Finally, create the rule and save changes.
GitHub Actions pricing
An important thing to be aware of, is the pricing for GitHub actions. Depending of the account type, a specific amount of free minutes(per month) and storage is included. Another important thing to know is that minutes for Linux, macOS and Windows virtual machines have a different value.
As an example, GitHub Free account have 2000 minutes included, depending on the type of machine you will have:
- Linux -> 2000 build minutes(minute multiplier is 1)
- Windows -> 1000 build minutes(minute multiplier is 2)
- macOS -> 200 build minutes(minute multiplier is 10)
Any extra minutes for builds or extra storage is billed by separate, you need to set a monthly spending limit, which will be used as soon as you spend all your included minutes of the month. This is an example of my organization billing. The value for macOS is 1010 but since the multiplier is 10, the real minutes we have used for build is 101.
I will continue writing new posts related to GitHub Actions and more. Possibilities are endless and a lot of things can be done, such static code analysis, deploy to a test and production environment, send apps to stores, run instrumented test on device farms, etc.
The GitHub repository for this example can be found here