This application aims to aid teachers by tracking the status and the results of homework submissions. The flow using GitHub yields milestones during the process of submission. These, possible points/grades from automated evaluations, and teachers grade overrides are tracked and recorded in this application.
This application is not stand-alone; it works with the other parts of the toolset in this repository, namely
- the GitHub Monitor application running as a GitHub App forwarding events to this application,
- and Publish Results to PR running in GitHub Actions workflows in student repositories pushing automatically evaluated results to this application.
The application requires the following mandatory configurations specified as environment variables.
AHK_CosmosAccountEndpoint and AHK_CosmosAccountKey: The endpoint name (URL) and the access key of the CosmosDB database used as backing data storage.
AHK_EventsQueueConnectionString: The connection string of the Azure Queue Storage used by GitHub Monitor to send grade events; e.g., DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
GitHub Monitor application translates webhook notifications from GitHub into status milestones. These milestones are recorded for each GitHub repository tracked by the system. These status milestones can be queried via an API.
When the automated evaluation is executed, the results are published using Publish Results to PR containerized application sending the results to a webhook of this application. The results are saved in a CosmosDB database. The process is visualized below:
In order to authorize requests the application requires a token, a HMAC-SHA256 signature, and the date in each request's header as follows:
X-Ahk-Token: The token is a string value known to this application (available in its database).X-Ahk-Sha256: The signature of the request (see below).Date: The date of sending the request in RFC1123 format.
To protect against replay attacks, the date of sending the request is expected in both the signature and request header. The server validates whether the provided date is current - a maximum skew of 10 minutes is tolerated.
The signature is based on a secret value paired with the token (also stored in the database). Multiple token-signature values are allowed. The application considers a request valid when the provided token is valid, and the signature matches the expected value computed with the token's corresponding secret.
The signature calculation algorithm is as follows:
- Write the following data as bytes to a temporary stream:
- The HTTP verb used to send the data. Must be uppercase.
- A single
\ncharacter. - The URL (with scheme, host, port, and path) the request is sent to. The value must be all lowercase. (Note, that in case the webhook is running behind a reverse proxy the application must be configured such that it receives the external, public address the request was sent to.)
- A single
\ncharacter. - The date of sending the request. Must be the same value sent in header.
- A single
\ncharacter. - The request payload
- Calculate the HMAC-SHA256 hash of the byte array composed in the previous step using the byte representation of the secret as initialization key.
- Get the base64 encoded string value of the hash. This string is the signature.
The previous use-case saves automatically evaluated results. If the teacher wants to override the points/grades GitHub Monitor accepts certain comments added to pull requests as commands. These commands, containing the grades/points are forwarded to this application via an Azure Queue Storage. The process is visualized below:
