Gitaction Board

Gitaction Board - Ultimate Dashboard for GithubActions.

Table of contents

• Usage
  • Pull docker image
  • Run docker image
    • Configurations
    • UI Dashboard
      • UI Dashboard Configurations
    • API
• Developers Guide
  • Prerequisites
  • Tests
  • Formatting
  • Security Checks
  • Run application locally
  • Build docker image

Usage

Pull docker image

docker pull ottoopensource/gitactionboard:<docker tag>

Run docker image

docker run \
  -p <host machine port>:8080 \
  -e REPO_OWNER_NAME=<organization/username> \
  -e REPO_NAMES=<repo names> \
  -it ottoopensource/gitactionboard:<docker tag>

Configurations

Environment variable name	Descriptions	Required	Default value	Example value
REPO_OWNER_NAME	Repository owner name. Generally, its either organization name or username	yes		webpack
REPO_NAMES	List of name of repositories you want to monitor	yes		webpack-dev-server, webpack-cli
GITHUB_ACCESS_TOKEN	Access token to fetch data from github. This is required to fetch data from a private repository	no
DOMAIN_NAME	Hostname of github	no	https://api.github.com
CACHE_EXPIRES_AFTER	Duration (in seconds) to cache the fetched data	no	60

Note: To create a personal access token follow the instructions present here and choose repo as a scope fot this token.

UI Dashboard

Gitaction Board has in-built UI dashboard to visualize the build status. You can access the following endpoint for the same

• http://localhost:<host machine port>

UI Dashboard Configurations

You can use the following query params to configure UI dashboard

Query param name	Descriptions	Required	Default value	Example value
hide-healthy	Hide all the healthy builds from the dashboard	no	false	true
max-idle-time	Configure the max idle time (in minutes), after the given time background polling for dashboard will stop	no	5	2
disable-max-idle-time	Disable background polling optimisation configured using max-idle-time	no	false	true

API

Once server is up, you can access the following endpoints to get the CCtray data.

Data in XML format

Access http://localhost:<host machine port>/v1/cctray.xml to get data in XML format

Sample response

<Projects>
    <Project name="hello-world :: hello-world-build-and-deployment :: talisman-checks" activity="Sleeping" lastBuildStatus="Success" lastBuildLabel="206" lastBuildTime="2020-09-18T06:11:41Z" webUrl="https://github.com/johndoe/hello-world/runs/1132386046"/>
    <Project name="hello-world :: hello-world-build-and-deployment :: dependency-checks" activity="Sleeping" lastBuildStatus="Success" lastBuildLabel="206" lastBuildTime="2020-09-18T06:14:54Z" webUrl="https://github.com/johndoe/hello-world/runs/1132386127"/>
    <Project name="hello-world :: hello-world-checks :: format" activity="Sleeping" lastBuildStatus="Success" lastBuildLabel="206" lastBuildTime="2020-09-18T06:11:41Z" webUrl="https://github.com/johndoe/hello-world/runs/1132386046"/>
    <Project name="hello-world :: hello-world-checks :: test" activity="Sleeping" lastBuildStatus="Success" lastBuildLabel="206" lastBuildTime="2020-09-18T06:14:54Z" webUrl="https://github.com/johndoe/hello-world/runs/1132386127"/>
</Projects>

Data in JSON format

Access http://localhost:<host machine port>/v1/cctray to get data in JSON format

Sample response

[
  {
    "name": "hello-world :: hello-world-build-and-deployment :: talisman-checks",
    "activity": "Sleeping",
    "lastBuildStatus": "Success",
    "lastBuildLabel": "206",
    "lastBuildTime": "2020-09-18T06:11:41.000Z",
    "webUrl": "https://github.com/johndoe/hello-world/runs/1132386046"
  },
  {
    "name": "hello-world :: hello-world-build-and-deployment :: dependency-checks",
    "activity": "Sleeping",
    "lastBuildStatus": "Success",
    "lastBuildLabel": "206",
    "lastBuildTime": "2020-09-18T06:14:54.000Z",
    "webUrl": "https://github.com/johndoe/hello-world/runs/1132386127"
  },
  {
    "name": "hello-world :: hello-world-checks :: format",
    "activity": "Sleeping",
    "lastBuildStatus": "Success",
    "lastBuildLabel": "206",
    "lastBuildTime": "2020-09-18T06:11:41.000Z",
    "webUrl": "https://github.com/johndoe/hello-world/runs/1132386046"
  },
  {
    "name": "hello-world :: hello-world-checks :: test",
    "activity": "Sleeping",
    "lastBuildStatus": "Success",
    "lastBuildLabel": "206",
    "lastBuildTime": "2020-09-18T06:14:54.000Z",
    "webUrl": "https://github.com/johndoe/hello-world/runs/1132386127"
  }
]

Developers Guide

Prerequisites

• jEnv
• Java 11
• Docker
• Hadolint
• ShellCheck
• Prettier
• talisman

Tests

Tests are separated into unit and integration test sets. To denote an integration test it needs to be annotated as @IntegrationTest.

To run only unit tests:

./gradlew test

To run integration tests:

./gradlew integrationTest

To run all the verifications:

./run.sh test

Test sets are runs in order, with unit tests first, followed by integration tests. Should there be a failure in the unit tests the task execution stops there, e.g. a prerequisite for running integration tests will be working unit tests.

Formatting

This project uses the following tools to follow specific style guide

• google-java-format-gradle-plugin for Java files
• Prettier for json, js, css, html and md files
• Hadolint for Dockerfile
• ShellCheck for sh files

To run format:

./run.sh format

Security Checks

This project uses the following tools to find security vulnerabilities

• org.owasp.dependencycheck to find vulnerable dependencies
• talisman to validate the outgoing changeset for things that look suspicious - such as authorization tokens and private keys.

To run OWASP dependency check:

./run.sh check

Run application locally

This service can be run locally. To run it locally, run the following command:

./run.sh run-locally <github auth token>

Build docker image

To build docker image run:

./run.sh docker-build

Release a new Docker image

A new docker image can be published to docker hub using CI/CD. To achieve the same we need to follow the following steps:

• Once changes are pushed to github, create a new release version

./run.sh bump-version <major|minor|patch>

• Push the newly created tag to github

git push origin "$(git describe --tags)"

NOTE: We are following semantic versioning strategy using io.alcide:gradle-semantic-build-versioning plugin