Github-CCTray

A lightweight App that provides all Github Workflows of a Repository in CCTray Specification.

Usecase

Visibility for your Github Actions & Workflows in one place.

You can use the App to configure CCTray Clients:

• CCMenu [tested]
• Nevergreen Dashboard [tested]

Running the App

Prerequisites

Authentication Token

To authenticate with Github API, the app needs a token, it can be provided by either of the following methods:

Github Personal Access Token

• FGPAT (recommended) or PAT
• Read-Only access to Actions (Workflows, workflow runs and artifacts) required for Private repos.
• You will need to set: GITHUB_TOKEN="<your_token>" as the environment variable.

Github APP (Recommened)

• Create a Github APP and grant Read-Only access to Github Actions
• The Github APP should be installed on the Github Organization or Account with access to the required repositories.
• You will need to set the following environment variables:

APP_AUTH_ID=<id_of_your_github_app>
APP_AUTH_PRIVATE_KEY_B64=<private_key_of_your_github_app_bas64_encoded>
APP_AUTH_INSTALLATION_ID=<installtion_id_once_installed>

• Please refer to Github's offical documentation to know what these values are and where can you find them

Please take into account the Github API rate limit for authentication tokens.

With Docker

Build the Docker image

docker build -t github-cctray:latest . 

Launch the Docker container

You can do this in two ways:

• Personal Access Token method

 docker run -p 8000:8000 \
            -e GITHUB_TOKEN="<your_token>" \
            -e BASIC_AUTH_USERNAME="<your_username>" \
            -e BASIC_AUTH_PASSWORD="<your_password>" \
            github-cctray:latest

• Github App method

 docker run -p 8000:8000 \
            -e APP_AUTH_ID="<id_of_your_github_app>" \
            -e APP_AUTH_PRIVATE_KEY_B64="<private_key_of_your_github_app_base64_encoded>" \
            -e APP_AUTH_INSTALLATION_ID="<installtion_id_once_installed>" \
            -e BASIC_AUTH_USERNAME="<your_username>" \
            -e BASIC_AUTH_PASSWORD="<your_password>" \
            github-cctray:latest --mode app-auth

Usage

Once up, the App binds to port 8000 by default and should be available at: http://localhost:8000

Making an HTTP request

The App accepts GET requests with following parameters:

manadatory parameters

• owner - Organisation or User who owns the repository
• repo - Name of the Repository

optional parameter

• token - If you want to use FGPAT per user to access the API, to overcome Github API rate limiting (this takes precedence over the token/Github App auth set in the env var).

For Example:

• Mandatory Parameters

curl -X GET http://localhost:8000?owner=<repo_owner>&repo=<repository_name>

• Optional Parameter

curl -X GET http://localhost:8000?owner=<repo_owner>&repo=<repository_name&token=<your_token>

Response

The above request would return an XML response (CCTray Specification) with all the workflows of a repository, while filtering them to return only Unique & Latest runs:

<Projects>
<Project name="github-cctray/CodeQL" activity="Sleeping" lastBuildStatus="Success" lastBuildTime="2023-05-07T23:22:02Z" webUrl="https://github.com/mansab/github-cctray/actions/runs/4909813101"/>
<Project name="github-cctray/Pylint" activity="Sleeping" lastBuildStatus="Success" lastBuildTime="2023-05-07T23:19:13Z" webUrl="https://github.com/mansab/github-cctray/actions/runs/4909813107"/>
<Project name="github-cctray/TestUnit" activity="Sleeping" lastBuildStatus="Success" lastBuildTime="2023-05-07T23:18:59Z" webUrl="https://github.com/mansab/github-cctray/actions/runs/4909813102"/>
</Projects>

Attributes are returned as follows:

Name	Description	Type
name	Name of the repository and the workflow	string : repo_name/workflow
activity	the current state of the project	string enum : Sleeping, Building
lastBuildStatus	a brief description of the last build	string enum : Success, Failure, Unknown
lastBuildTime	when the last build occurred	DateTime
webUrl	Exact URL of the Github Action run for a workflow	string (URL)
lastBuildLabel	Short commit ID associated with the last workflow run	string : Git SHA (8 char)

Health check

The App has an health endpoint which returns the status and version of the app

curl -X GET http://localhost:8000/health

Response

{"status":"ok","version":"2.2.0"}

Rate Limiting

Github has Rate Limiting for their APIs, to check if you are rate limited, use this endpoint

• With token in the environment variable

curl -X GET http://localhost:8000/limit

• With token in the query parameter

curl -X GET http://localhost:8000/limit?token=<your_token>

Response

{"rate_limit":{"limit":5000,"remaining":1724,"reset":1686920826,"reset_cest":"2023-06-16 15:07:06 UTC+02:00+0200","used":3276},"status":"ok"}

Development Setup

• Python 3.9
• pip
• Activate Python virtualenv

python -m venv venv
source venv/bin/activate

• Install requirements

pip install -r requirements.txt

• Execute

* set necessary env variable to authenticate with Github (see Prerequisites)
* export BASIC_AUTH_USERNAME=<user>
* export BASIC_AUTH_PASSWORD=<pass>
* python app.py --mode [pat-auth|app-auth] # pat-auth is the default mode if no mode is set