JS tool + React web application called chain-status that allows us to centralize, expose, consume and filter information about Github Pull Requests and Jenkins jobs status as a web page resource. The JS tool basically consumes information from Github API or Jenkins API and generates a JSON file which is retrieved by the React web application.
The best part here is everybody can easily use it for their projects, no additional source code is required and we are using external and free resources (like Github API jobs and Github Pages).
If you want to learn this tool directly from concrete, working examples we suggest to take a look at droolsjbpm-build-bootstrap project. This project integrates the chain-status
tool as Github workflows in order to provide a Kiegroup status page that is continuously updated in an automated way.
- droolsjbpm-build-bootstrap, a working and complete example of a real application.
- chain-status-example, a step by step simple example of how to integrate the tool.
It is multipackage npm project managed using Lerna.
- webpage, providing a React web application (see more details)
- action, JS tool for the data generation (see more details)
We recommend to use yarn, since just yarn.lock files are provided.
In the project directory, you can run:
To install the libraries
Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.
The page will reload if you make edits.
You will also see any lint errors in the console.
This project provides a set of actions that can be referenced by external projects workflows that aims to automate the Github page and content generation.
The generate-app action, the definition of which can be found here, is in charge to create the webpage that will be hosted at https://<your-account>.github.io/<repository>/
.
Here the main important steps performed by generate-app action:
- Checkout in the branch where you want to store the webpage code and content, the default is
gh-pages
. [the first time you run this action there will be no webpage] - Checkout in the original chain-status repository, i.e., this one.
- Setup nodejs and build the webpage using
yarn
. - Check if in the target branch (e.g.,
gh-pages
) there are old content/configuration files by checking thedata/
folder. If there exists, it copies its content under the newly compiled webpage (under./packages/webpage/public/
). - Deploy the created page using gh-pages tool in the target branch (e.g.,
gh-pages
).
Field | Required | Default | Description |
---|---|---|---|
github-token | true | The Github token that must be used to interact with Github API | |
info-md-url | true | The url pointing to a Markdown file used to populate info section | |
gh-pages-branch | false | gh-pages | The branch used by gh-pages tool, where the webpage will be stored |
The generate-data action is in charge to create and store the content that is then fetched by the webpage. It stores all needed information in the data/
folder.
Here the main important steps performed by generate-data action:
- Checkout in the branch where you want to store the webpage code and content, the default is
gh-pages
. - Execute the chain-status tool that, given a set of inputs, compute the configuration files and all the contents that are used by the webpage.
- Commit and push the newly generated data in the target branch (e.g.,
gh-pages
).
Field | Required | Default | Description |
---|---|---|---|
github-token | true | The Github token that must be used to interact with Github API | |
definition-file | true | The file containing all projects for which you want to provide the status, an example - more infos here | |
title | false | Project status | The project/webapp title |
subtitle | false | Contribution status | The project/webapp subtitle |
base-branch-filter | false | A comma separated list of base branches RegEx to be filtered. Like main,7.59.x,8.x or main,^7.* |
|
project-filter | false | A comma separated list of project RegEx to be filtered. Like drools,opta.* or jbpm,^drools.* |
|
created-by | false | github action | The user/machine/whatever that regenerates the report |
created-url | false | Normally the job generating the info URL | |
logger-level | false | info | The log level. 'info' (default) | 'trace' | 'debug' |
gh-pages-branch | false | gh-pages | The branch used by gh-pages tool, where the webpage will be stored |
branches | false | [] | The list of branches for which to provide branches comparison |
Since this project is already providing configurable actions (more details in actions section), if you want to use this tool - in order to automate the Github page generation for project statuses - you will only have to add two specific workflows to your target project and configure it as you prefer.
In order to properly use this tool you have to accomplish the following prerequisites:
- Add Github token to you account, more information on how to do it here.
- Add default personal Github page repository (
<profile/org>.github.io
), more information here.
Here the steps you should follow to integrate your project with chain-status tool:
-
Create a new Github workflow for the webpage generation.
- Create a new file in
.github/workflows/generate_status_page.yaml
(you can use whatever name you prefer) - Copy the following content in the file
name: Generate status page on: workflow_dispatch jobs: generate-status-page: if: github.repository_owner == '<OWNER>' concurrency: group: generate-status-page cancel-in-progress: true strategy: matrix: os: [ubuntu-latest] fail-fast: true runs-on: ubuntu-latest name: Generate status page steps: - name: Generate status page uses: kiegroup/chain-status/.ci/actions/generate-app@main with: info-md-url: "<PATH-TO-INFO>" github-token: "${{ secrets.GITHUB_TOKEN }}"
- Change some input fields in according to your projects, for instance
OWNER
must be the owner of the project where you are adding this workflow.
- Create a new file in
-
Create a new Github workflow for the report/data generation.
- Create a new file in .github/workflows/generate_status_page_data.yaml (you can use whatever name you prefer)
- Copy the following content in the new workflow
name: Generate status page data on: workflow_dispatch: schedule: - cron: '0 * * * *' jobs: generate-status-page-data: if: github.repository_owner == '<OWNER>' concurrency: group: generate-status-page-data cancel-in-progress: true strategy: matrix: os: [ubuntu-latest] fail-fast: true runs-on: ubuntu-latest name: Generate status page data steps: - name: Generate status page data uses: kiegroup/chain-status/.ci/actions/generate-data@main with: definition-file: https://raw.githubusercontent.com/kiegroup/droolsjbpm-build-bootstrap/main/.ci/pull-request-config.yaml title: <TITLE> subtitle: <SUBTITLE> base-branch-filter: <BRANCH-LIST> created-by: Github Action created-url: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} logger-level: debug github-token: "${{ secrets.GITHUB_TOKEN }}"
- Replace
<..>
data with your project-specific one, for further details about fields usage see Generate Data action. - [Optional] Include
schedule
option only if you aim to automatically tun the Github action periodically - this is recommended if you want to have the status data always up to date.
-
Once both workflows have been created I recommend running first the content generation one (
generate_status_page_data
), such that the projects configuration that you want to use is already present when you create the webpage content (using thegenerate_status_page
workflow).