A lightweight App that provides all Github Workflows of a Repository in CCTray Specification.
Visibility for your Github Actions & Workflows in one place.
You can use the App to configure CCTray Clients:
- CCMenu
[tested]
- Nevergreen Dashboard
[tested]
To authenticate with Github API, the app needs a token
,
it can be provided by either of the following methods:
- 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.
- 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.
docker build -t github-cctray:latest .
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
Once up, the App binds to port 8000
by default and should be available at: http:https://localhost:8000
The App accepts GET requests with following parameters:
manadatory parameters
owner
- Organisation or User who owns the repositoryrepo
- 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:https://localhost:8000?owner=<repo_owner>&repo=<repository_name>
- Optional Parameter
curl -X GET http:https://localhost:8000?owner=<repo_owner>&repo=<repository_name&token=<your_token>
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) |
The App has an health endpoint which returns the status and version of the app
curl -X GET http:https://localhost:8000/health
{"status":"ok","version":"2.2.0"}
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:https://localhost:8000/limit
- With token in the query parameter
curl -X GET http:https://localhost:8000/limit?token=<your_token>
{"rate_limit":{"limit":5000,"remaining":1724,"reset":1686920826,"reset_cest":"2023-06-16 15:07:06 UTC+02:00+0200","used":3276},"status":"ok"}
- 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