Create your first GitHub Action

Create a repository

GitHub Actions have to be hosted in a GitHub repository that is dedicated to the action.

Thus the first step in the creation of a GitHub Action is to create a new GitHub repository. Create a completely empty repository (e.g. no README nor .gitignore nor license file), that will make the next steps easier. You can add them later on.

Do not initialize or clone the repository. We will initialize a local Git repository and push it to GitHub in the following steps.

The full name of your repository (either username/repository-name or org-name/repository-name) is going to be useful in the next step so keep it handy. In the following sections, we will consider it named my/action-github-repository.

If you created a private repository to host your action, make your action visible to your other private repositories by following these instructions.

Note that actions stored in private repositories are not runnable in public repositories.

Initialize your Quarkus application

A Quarkus GitHub Action is a standard Quarkus application.

You can create one including the Quarkus GitHub Action extension with the following command:

Make sure you use the 📋 button to copy the command.

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.4.Final:create \
    -DplatformVersion=2.16.4.Final \
    -DprojectGroupId=org.acme \ (1)
    -DprojectArtifactId=my-github-action \ (2)
    -DprojectVersion=999-SNAPSHOT \ (3)
    -DprojectName="My Action" \ (4)
    -DprojectDescription="Description of my action" \ (5)
    -Ddata="github-action-codestart.github-repository=my/action-github-repository" \ (6)
    -Dextensions="io.quarkiverse.githubaction:quarkus-github-action:1.0.3" (7)

1	The groupId of your Maven project.
2	The artifactId of your Maven project.
3	The version of your Maven project. Let’s make it a rolling version.
4	The name of the action. It is used both in the `pom.xml` and in the metadata of the action.
5	The description of the action. It is used both in the `pom.xml` and in the metadata of the action.
6	The full name of the GitHub repository hosting the action (in the form `username/repository-name` or `org-name/repository-name`).
7	The Quarkus GitHub Action extension. Add it from the creation so that it can generate a full Quarkus GitHub Action application using Codestarts.

On Windows and macOS, it is recommended to concatenate all the options on one line (without \), as the \ might not be correctly interpreted.

This command creates a regular Quarkus Maven project. You can add additional Quarkus extensions or Java dependencies.

Once the project is created, go to the my-github-action directory:

cd my-github-action

Push to GitHub

If you have followed carefully the instructions above, you should be in your newly created project directory.

The next step is to push your GitHub Action to its GitHub repository (GitHub describes the instructions in the repository page):

git init
git add .
git commit -m "Init the project"
git branch -M main
git remote add origin git@github.com:my/action-github-repository.git (1)
git push -u origin main

1	Replace `your/github-repository` with the full name of the repository you created to host the GitHub Action.

Be careful to strictly follow the organization of the created project: the action.yml file must be at the root of your repository.

Once you pushed the repository to GitHub, the Publish action artifact to GitHub project’s Maven repository workflow will automatically publish your action to the Maven repository of the action’s repository.

Wait for it to complete before using your action. Go to the Actions tab of your action’s repository to check the workflow status.

When pushing new code to your action, the action will be updated only after the Publish action artifact to GitHub project’s Maven repository was completed successfully.

Let’s take a step back

Now is a good time to take a step back and have a closer look at what we pushed to the repository:

.
├── README.md (1)
├── mvnw (2)
├── mvnw.cmd (2)
├── pom.xml (3)
├── action.yml (4)
├── action.docker.yml (5)
└── src
    └── main
        ├── docker (6)
        │   ├── Dockerfile.jvm
        │   ├── Dockerfile.legacy-jar
        │   ├── Dockerfile.native
        │   └── Dockerfile.native-micro
        ├── java
        │   └── org
        │       └── acme
        │           └── MyAction.java (7)
        └── resources
            └── application.properties (8)

1	The root `README.md`. Add some content here so that users can understand what your GitHub Action does.
2	The Maven wrapper.
3	The `pom.xml` descriptor as we created a Maven project. Nothing specific here except a `<distributionManagement>` deploying the artifact to the repository’s Maven repository.
4	The `action.yml` descriptor, more on that later.
5	An alternative `action.yml` if you want to use a Docker-packaged native executable, more on that later.
6	Some default Dockerfiles provided for Quarkus. Only useful if using `action.docker.yml`.
7	A simple GitHub Action example.
8	An `application.properties` with some default configuration properties to silence Quarkus at startup (no banner, only log errors).

action.yml

action.yml is the GitHub Action descriptor and it is important to understand what it is doing.

The default one you obtain when creating a GitHub Action as described above is the following:

name: 'My Action' (1)
description: 'Description of my action' (2)
inputs:
  github-token: (3)
    description: 'GitHub token'
    required: true
runs:
  using: "composite" (4)
  steps:
    - run: curl -Ls https://sh.jbang.dev | bash -s - app setup (5)
      shell: bash
    - run: ~/.jbang/bin/jbang --repos 'github=https://maven.pkg.github.com/my/action-github-repository/' --repos 'mavencentral' org.acme:my-github-action:999-SNAPSHOT (6)
      shell: bash
      env:
        JSON_INPUTS: ${{ toJSON(inputs) }} (7)
        GITHUB_TOKEN: ${{ inputs.github-token }} (8)

1	The name of the action passed at creation.
2	The description of the action passed at creation.
3	The GitHub token is mandatory if you stick to publishing the action Maven artifact to the GitHub hosted Maven repository.
4	The action is a composite action which has a few specificities. You can add additional steps if required.
5	Install JBang, which is used to run the jar file.
6	Execute the jar file. It is downloaded from the Maven repository of the action GitHub repository.
7	Inputs are not transmitted to composite actions so we need to push them manually. The action will deserialize the JSON input automatically and make the inputs available.
8	The token is required to download the artifact from the GitHub hosted repository and will be used to authenticate the GitHub clients you can inject in your action code.

A composite action can be executed on all sorts of hosts, Linux, macOS or Windows.

Given it is a composite action, you can add additional steps to the action.

You can also tweak the existing steps of the action. For instance, if you want to use a Java version different from the one installed by default for executing your code, you can adjust the setup-java step as follows:

    - name: Set up JDK 20
      uses: actions/setup-java@v3
      with:
        java-version: 20
        distribution: temurin

Docker container action alternative

Another alternative is to build a Docker image with your application and use it as a Docker container action.

In the generated application, we provide both an alternative action.docker.yml (that you need to rename to action.yml) and a workflow file to publish the Docker image to the Docker repository of the action repository.

Using Docker container actions comes with some constraints as you can only run them on Linux hosts.

It is a limitation of GitHub Actions.

Except if you have specific requirements, it is recommended to use the default composite action approach.

application.properties

The default application.properties contains some configuration properties to make Quarkus startup silent:

quarkus.log.category."io.quarkus".level=SEVERE
quarkus.banner.enabled=false

MyAction.java

This file is just an example of a very simple action:

package org.acme;

import io.quarkiverse.githubaction.Action;

public class MyAction {

    @Action
    void action() {
        System.out.println("Hello from Quarkus GitHub Action");
    }
}

The action() method will be called when the action is run on GitHub Actions and will print the message to the output.

Run your action

From there, everything is ready to run your simple GitHub Action, provided you waited for the Publish action artifact to GitHub project’s Maven repository initial workflow run of your action’s repository to finish.

To check if the Publish action artifact to GitHub project’s Maven repository workflow has run successfully, go to the Actions tab of the action’s repository.

Create a workflow in a separate repository with the following step:

      - name: Run my action
        uses: my/action-github-repository@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Next steps

Obviously, you can do a lot more with Quarkus GitHub Action and we describe all its features in the Developer reference.