How to Create a GitHub Action for Gradle [Full Tutorial]

Gradle is a flexible build automation tool for languages such as Java, C++, and Groovy. It takes raw source files and compiles them into an executable application.

GitHub Actions allow you to perform many operations within the GitHub Actions continuous integration and continuous delivery (CI/CD) platform that you can trigger when creating pull requests or merging code. These actions can automate common tasks like running tests and version-tagging code.

Furthermore, integrating Gradle with your pipeline allows you to run Gradle commands as an action. You can find many available actions on the GitHub Marketplace. However, this article mainly focuses on how to build your own action to trigger a Gradle build of a Java application.

How to Use Gradle as an Action

There are many types of actions. For example, Docker actions use Docker to create the environment the action runs on. Meanwhile, JavaScript actions run natively in a GitHub instance while composite actions combine multiple actions into one. This tutorial will focus on Docker actions.

Creating a Docker Action

Using Docker is more flexible than implementing JavaScript-only actions, as you have more control over the environment and, subsequently, over which applications and libraries you can use.

To create a Docker action, start by creating a new folder, which will contain the three files:

• Docker file
• YAML configuration file
• Action script file

Let’s start with the action script file. Create a new file named gradle_build.sh and add the following code:

This is a simple shell script that runs the gradle build command. If the build command succeeds, the script will obtain the name of the .jar file it produces and outputs its location. If the command fails, the script exits the action.

The $1 is the input variable you will configure in the next step. Furthermore, the property name and value in the output string will be declared in the configuration file later on.

Now, create a file with the following contents and give it the name Dockerfile. Then insert the following content.

This Dockerfile describes how to build the environment for running your action. The first line tells Docker to use the latest pre-existing Gradle image from Docker Hub. This ensures you have everything required to run Gradle. The next command copies the gradle_build.sh script from the previous step into the Docker container. Finally, the code tells Docker to run this script on startup.

Now you must create a config file that defines the inputs and outputs and how they should run. Name this file action.yml and add the following contents.

This config file passes an input parameter called option to your script and outputs a property called jar-location.

You can use a number of Gradle options when running your action, even stringing multiple actions together. This is because your option input is just a string passed directly after the gradle build command.

For example, you could set the option parameter to the following:

In response, your action would execute the following command:

The final step is to push and tag the code in GitHub to use as an action in other repositories.

First, create a public GitHub repository to host an action called gradle-github-action. Next, push the changes to the main branch and tag the changes with the tag v1.

This creates a v1 tag for the repository that you can reference when calling your action. Any time you update your action in the future, you can release a new version using a new tag so that the changes don’t impact projects using previous versions.

Using the Gradle Action

Now, you use this Gradle Action in a Java project to build and test your code. First, download the sample Java project and open the empty GitHub workflow file in .github/worfklows/main.yml.

Next, add the following to the main.yml file:

This configuration tells your workflow to run on both push and pull requests.

The workflow that runs gradle_build_job has multiple steps. The first step uses the checkout action to check changes on the server. Next, it runs the gradle build action created in the previous section.

You can also use the option parameter to pass in build options when running the action. To call the action, you must replace <your_github_account> with your GitHub account name.

The final step only runs on pull requests to upload the .jar file using the upload-artifact action provided by GitHub. To use it, you must give a name to the artifact and file path from the gradle-github-action output. The upload-artifact action then uploads that artifact to GitHub.

Save the file and then initialize the sample project as a GitHub repository. Check out a new branch to commit to and push your changes. When you push the code, open the repository in GitHub and look at the workflow output on the Actions tab.

The output should show the steps that have run, including the code checkout and the Gradle Build step. The upload artifact step is listed as skipped because you haven’t yet created a pull request.

Now, make a pull request for this branch and view the summary of the workflow run.

In the summary, you should see that the workflow is finished and that the .jar file is listed under the name jar-file (as specified in the workflow config file). This file is now available for other team members to access without having to download and build the code.

By creating your own action, you have complete control over its functionality and can tailor it to your specific needs. This can be especially useful if you have unique requirements or workflows not covered by existing actions.

Furthermore, once you have developed an action, you can reuse it in multiple projects. Furthermore, if you make your action open source, other developers can use it in their projects and even contribute to its development. This can build a community around your action and leverage the expertise of others.

Gradle’s Own GitHub Build Action

The previous examples showed how to create actions. However, many pre-built GitHub actions are available on the GitHub Marketplace.

Like the action you just created, Gradle developed the gradle-build-action to run Gradle builds as part of a GitHub workflow.

To add this pre-built action to your workflow, use the following code:

The gradle-build-action is a valuable tool for automating Gradle builds as part of a GitHub workflow, allowing you to build, test, and publish your Gradle projects. As this tool is developed and maintained by the Gradle team, it provides much more flexibility than manually created actions.

Using GitHub Actions for Gradle 

In this post, you built a manual GitHub Action that executes the gradle build command. You used Docker to set up the environment and configured inputs and outputs for the action before using the GitHub action in a sample project. Finally, you compared our custom Action to the official gradle-build-action.  

Manually building a GitHub action offers several benefits over pre-built actions. By building actions manually, you have complete control over the behavior and functionality of the actions, allowing you to tailor them to their specific needs. Additionally, building actions manually can lead to more efficient and streamlined workflows, as users can design their actions to work seamlessly with their existing codebase and processes.

However, for everyday actions like building and testing Gradle projects, using the already available gradle-build-action from the GitHub Marketplace provides a more streamlined process for integrating Gradle into your GitHub pipelines.