Skip to content

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

License

Notifications You must be signed in to change notification settings

mansab/github-cctray

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

98 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Github-CCTray

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

STATUS STATUS STATUS

Usecase

Visibility for your Github Actions & Workflows in one place.

You can use the App to configure CCTray Clients:

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_github_token>" as the environment variable.

Github APP (Recommened)

  • Install cctray-auth Github APP to grant Read-Only access to Github Actions on Personal or Organization repositories.
  • After installation, you will need to authorize the app and get a Github APP token as described below.

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

Github APP grants Read-Only access to repository Metadata & Actions

With Docker

Pull the Docker image

docker pull ghcr.io/mansab/github-cctray:v4.0.0

or Build it yourself

docker build -t github-cctray:latest . 

Launch the Docker container

You can do this in either of the two methods below:

Personal Access Token method
 docker run -p 8000:8000 \
            -e GITHUB_TOKEN="<your_github_token>" \
            -e LOGIN_USER="<set_username>" \
            -e LOGIN_PASSWORD="<set_password>" \
            github-cctray:latest
Github App method
  1. Start the container
 docker run -p 8000:8000 \
            -e LOGIN_USER="<set_username>" \
            -e LOGIN_PASSWORD="<set_password>" \
            github-cctray:latest --mode app-auth
  1. Obtain the Github APP token by accessing: http://localhost:8000/auth (this will start the authentication process)

  2. Follow the instructions provided in the docker console to activate your device/service & obtain the token.

  3. Restart the docker container with the token obtained in step 3.

 docker run -p 8000:8000 \
            -e GITHUB_APP_TOKEN="<github_app_token>" \
            -e LOGIN_USER="<set_username>" \
            -e LOGIN_PASSWORD="<set_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_github_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_github_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

python3 -m venv venv
source venv/bin/activate
  • Install requirements
cd src
pip install -r requirements.txt
  • Execute
* set necessary env variable to authenticate with Github (see Prerequisites)
* export LOGIN_USER=<user>
* export LOGIN_PASSWORD=<pass>
* python3 app.py --mode [pat-auth|app-auth] # pat-auth is the default mode if no mode is set