Testing Github Actions workflows for Android locally with Docker

Image by Freddy from Pixabay

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

1. Download and install Docker Desktop
2. 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 .yml file.

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: android-actions/setup-android@v2.0.10

Set ANDROID_HOME

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:

ANDROID_HOME=/root/.android/sdk

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 aGITHUB_TOKEN or 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:

GITHUB_TOKEN=your_generated_token
PACKAGES_READ_TOKEN=your_generated_token

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:

SOME_API_KEY="\"your_api_key\""

This is because of the way BuildConfig field generation works for strings.

NOTE 2: from security point of view it’s a good idea to give the Github tokens a limited lifetime by setting an expiry date. Just be aware that when you run act and you see this error:

Error: authentication required

it means that probably one of your tokens has expired. Go to your Github developer settings, regenerate the token and replace it in the .secrets file.

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/upload-artifact or 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:

mkdir /tmp/artifacts

and then pass this directory to act using the parameter --artifact-server-path :

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

act

That’s it! Happy testing your workflows!