= quarkus-ecosystem-ci :plantuml: http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/quarkusio/quarkus-ecosystem-ci/master/

image:https://img.shields.io/github/issues/quarkusio/quarkus/triage/ci-participant?label=ci-participant%20issues&logo=quarkus[link=https://github.com/quarkusio/quarkus/labels/triage%2Fci-participant]

Repository used for orchestrating cross-CI builds of extensions part of Quarkus ecosystem/universe.

== What it's all about

It's in everyone's interest to know if Quarkus extensions and especially participants in the https://github.com/quarkusio/quarkus-platform[Quarkus Platform] build properly against the latest Quarkus, since Quarkus moves very fast. At the same time, due to resource constraints it is not possible for every extension to run their tests in the Quarkus organization. In that vein Quarkus has come up with a solution that allows both Quarkus contributors and Quarkus Platform participants to know each day whether their extension works with the latest Quarkus or not, while sharing the CI load amongst platform participants. Furthermore, the solution aims to be as frictionless as possible for Quarkus Platform participants while also not requiring said participants to trust Quarkus with their GitHub tokens.

This repository contains the metadata that needs to be set up for a platform participant to have their CI automatically triggered and post the result on a Quarkus issue.

image::{plantuml}/ci-overview.puml[CI Overview]

== What do I need to do as a Quarkus Platform participant

After your extension has been added to the Quarkus Platform, you will additionally need to do the following:

1. Open an issue in https://github.com/quarkusio/quarkus/issues[the Quarkus issue tracker], where updates will be posted (the CI job will close or open the issue depending on the CI outcome). For Quarkiverse extensions, it is suggested to use https://github.com/quarkiverse/quarkiverse/issues[the Quarkiverse issue tracker]. An example of such an issue can be found https://github.com/quarkusio/quarkus/issues/8593[here].

Note that in one of the following steps you will need to configure a GitHub token for the user who created the issue in your extension repository. The user can be a regular user (for example the author of the extension) or a bot. This is so the automation can open/close the issue.

2. Open a Pull Request to this https://github.com/quarkusio/quarkus-ecosystem-ci[quarkus-ecosystem-ci] repository where you add a directory for your extension and inside it place a file named info.yaml. Name of the directory is not important, just attempt to follow same naming conventions used for similar projects.

The file needs to contain the following information: + [source,yaml]

url: https://github.com/someorg/my-extension # Github repo of your extension issues: repo: quarkusio/quarkus # this should be left as is when CI updates are going to be reported on the Quarkus repository latestCommit: 123456 # this is the number of the issue you created above

An example of the above configuration can be found https://github.com/quarkusio/quarkus-ecosystem-ci/blob/419a6c18312ac26ab0213ae1bf0ee6d38a550f4e/qpid/info.yaml[here].

=== What if my repository is not in the Quarkiverse organization?

The following steps are only needed if your project is NOT a Quarkiverse participant (i.e. not a project of the https://github.com/quarkiverse[Quarkiverse] organization), as Quarkiverse projects are already set up this way:

• Add a secret named ECOSYSTEM_CI_TOKEN in your repository that contains the token of the user that opened the issue mentioned in the first step. This token will be used in order to open and close the issue from the CI action.

• Add the following file to configure the Quarkus CI in GitHub Actions for your repository:

.github/workflows/quarkus-snapshot.yaml (this file contains the actual GitHub Actions declaration) + [source,yaml]

name: "Quarkus ecosystem CI" on: watch: types: [started] workflow_dispatch:

For this CI to work, ECOSYSTEM_CI_TOKEN needs to contain a GitHub with rights to close the Quarkus issue that the user/bot has opened,

while 'ECOSYSTEM_CI_REPO_PATH' needs to be set to the corresponding path in the 'quarkusio/quarkus-ecosystem-ci' repository

env: ECOSYSTEM_CI_REPO: quarkusio/quarkus-ecosystem-ci ECOSYSTEM_CI_REPO_FILE: context.yaml JAVA_VERSION: 11

#########################

Repo specific setting

#########################

ECOSYSTEM_CI_REPO_PATH: FIXME # TODO: this needs to be set to the directory name added in 'quarkusio/quarkus-ecosystem-ci'

###################################

Optional repo specific settings

###################################

The setup-and-test script assumes the pom.xml file is at the root of your repo

Use this env var to add a nested path within your repo where pom.xml is

QUARKUS_VERSION_POM_PATH: PATH_WHERE_POM_XML_IS

The setup-and-test script assumes the property within pom.xml that determines the

quarkus version is called "quarkus.version".

Use this env var to override the property to something else

(like "quarkus.platform.version" for example)

QUARKUS_VERSION_POM_PROPERTY: quarkus.version

jobs: build: name: "Build against latest Quarkus snapshot" runs-on: ubuntu-latest if: github.actor == 'quarkusbot' || github.event_name == 'workflow_dispatch'

steps:
  - name: Install yq
    uses: dcarbone/[email protected]

  - name: Set up Java
    uses: actions/setup-java@v3
    with:
      java-version: ${{ env.JAVA_VERSION }}
      distribution: 'temurin'

  - name: Checkout repo
    uses: actions/checkout@v3
    with:
      path: current-repo

  - name: Checkout Ecosystem
    uses: actions/checkout@v3
    with:
      repository: ${{ env.ECOSYSTEM_CI_REPO }}
      path: ecosystem-ci

  - name: Setup and Run Tests
    run: ./ecosystem-ci/setup-and-test
    env:
      ECOSYSTEM_CI_TOKEN: ${{ secrets.ECOSYSTEM_CI_TOKEN }}

Finally, if your extension requires a custom test script (by default quarkus-ecosystem-test from this repository is used), add a file named .github/quarkus-ecosystem-test.

Example projects containing the proper GitHub Action YAML file (and which has been tested with the whole process) can be found https://github.com/geoand/quarkus-qpid-jms/blob/51a03f41c38ea43dedf05c25e2277dbf99d88d50/.github[here] and https://github.com/quarkusio/quarkus-platform/tree/main/.github[here].

=== How to create a token for use with Ecosystem CI

In case you haven't created a GitHub token before, the process is roughly as follows.

You can generate a token by accessing https://github.com/settings/tokens and clicking on Generate new token. On the page that comes up, provide a name, select repo scope and click on Generate token at the bottom of the page. You will be prompted with the newly generated token, but be sure to copy it wherever it is needed, because you won't be able to see it again.

Now that you have created the token, you need to create a GitHub Secret with its value, by first accessing /settings/secrets in your repository, then adding a new secret named ECOSYSTEM_CI_TOKEN where you simply paste the contents of the token and save by clicking on Add token.

=== What if I need to a custom setup?

You can execute a custom script as part of the Ecosystem CI initialization (i.e. before the build of your repository starts) by adding an executable bash script .github/ci-init.sh to your repository.

== How come this works?

The "trick" (more like a hack actually) is that Quarkus Platform participant's GitHub Actions are triggered when the Quarkus Ecosystem CI stars the extension repository. Furthermore, before starring the repository, some context information is written to this repository which is then meant to be read in the triggered Github Action. This way this Quarkus Github Action does not need to hold any secrets for the participants.