When you edit your Github Actions workflows it would be nice to have a possibility to test them locally to have a quick feedback loop if something is broken. Otherwise you have to wait for Github Actions to run the action (which in case of sprint builds or Play Store release builds may not happen for weeks) only to later realize that the modified workflow has an error and doesn’t run when it’s most needed.
This is possible using Docker and a local action runner called act.
The guide below is specifically meant for testing workflows of Android apps on a Mac, but should be easy enough to adjust to other platforms.
Install Docker Desktop and act
- Download and install Docker Desktop
- Install act:
brew install act
Prepare your project
Act runs your workflows by default from the
.github/workflows directory. That means you need to run act from your project root directory.
However, act doesn’t know anything about your project-specific Github environment variables, project secrets or Android SDK you’re using to build your project. So you have to first prepare your project.
Setup Android SDK
As the act Docker image doesn’t come with an Android SDK preinstalled, you can work around this by temporarily adding the setup-android action to your workflow
Just add the two lines to your workflow (make sure you don’t commit them as your Github Actions runners probably already have the Android SDK preinstalled):
- name: Setup Android SDK uses: email@example.com
Unfortunately the setup-android action doesn’t set the
ANDROID_HOME environment variable automatically.
To do it yourself, you can create an
.env file in your project root folder which will contain your environment variables.
The file should contain the following line:
Remember to add the
.env file to your
.gitignore, as it’s only needed locally.
Setup project secrets
Github Actions workflows often require the
GITHUB_TOKEN and other project related secrets (e.g.
PACKAGES_READ_TOKEN, different API keys your app uses etc.).
You can setup all your project secrets inside a
.secrets file in your project root folder.
IMPORTANT: make sure to add the
.secrets file to
.gitignore, as your secrets should never be committed and pushed to Github!
To generate a
PACKAGES_READ_TOKEN you have to go to your Github Developer Settings, generate a new Personal Access Token, copy it and make sure you have authorized the token to access the relevant organization your repository lives in (if required).
Then inside the
.secrets file you can add your secrets like this:
NOTE: if you define in your project any string variables, which are then converted in your
build.gradle.kts files into
BuildConfig fields, you need to put them in internal escaped quotes
\" and then again in external quotes
" like this:
This is because of the way
BuildConfig field generation works for strings.
Running the actions locally
To run the actions, first open the terminal and change the current directory to your project’s root directory.
If you don’t specify otherwise, act will dispatch the
push event to trigger your workflows. You can also dispatch other events — see more options.
Running using artifact server
If you are using
actions/download-artifact in your workflow, you need to create a local directory on your computer, which will be used for a simulated artifact server:
and then pass this directory to act using the parameter
act --artifact-server-path /tmp/artifacts
This will run the workflows in your project and output all artifacts to the specified directory, where you can later inspect them.
Running without an artifact server
Simply go to your project and run
That’s it! Happy testing your workflows!
This article was originally published on proandroiddev.com on December 16, 2022