This repository holds the source code to the pull request pre-processing bot that processes student submission to Github in the National University of Singapore, School of Computing CS2103: Software Engineering class.
There are two goals the bot is achieving for the CS2103 Teaching Team:
- Ensures that students provide sufficient information on their pull requests so that the bot can identify the students' tutors and assign the tutors to the correct pull request for reviewing purpose.
- Ensures that students submit their pull requests to the correct repository, given that there is a distinction between repositories on
se-eduvs the repositories forked for the semester.
The bot uses Accuser, a library that enables this bot to process PRs and issues on repositories we selected.
The Github access token is to be stored in an environment variable called GITHUB_TOKEN. Tokens can be created and managed for nus-se-pr-bot by signing to the account and visiting Settings > Developer Settings > Personal Access Tokens. Do not commit the token into the repository for security reasons. You may create a file .env in the root folder of this repository to set the environment variables for this bot.
Write permissions is required by the bot for tutor assignment, label application and pull request closure.
The current semester's Github account / organization name can be set in the config.json, along with the highest level of addressbook (1-4) repository available to the students in the currentLevel setting in the same file.
There are two main way of getting information about the repositories that the bot is watching: webhooks or interval polling.
Webhooks require the bot to expose a HTTP URL endpoint which Github can perform a HTTP request to whenever there are new changes to the repository. Specifically for Github, new PRs can be received as notifications through this endpoint. This can be thought of as a push model. However, having an unsecured HTTP resource available to the internet may subject the bot to spam or denial of service attacks. The need to secure the HTTP resource may also pose additional requirements which may be out of scope for the bot. Furthermore redelivery of failed delivery of events is not supported by Github.
Interval polling on the other hand would require the bot to request information periodically from Github through their API resources. Authentication is handled by giving the bot access to a Github account which has read/write access to all the repositories it processes. However, the bot has to determine which pieces of information are new and which were previously processed. This can be seen as a pull model.
In our case, NUS SE PR Bot employs the interval polling method to retrieve pull requests' information from Github on those repositories that the bot is watching. The bot is currently registered on Github with the handle nus-se-pr-bot. All comments sent from the bot will be shown from that account. The authentication details of the account are currently with Prof Damith and a Github authentication token (env variable GITHUB_TOKEN) is used for automated access to Github. By default, the bot will poll Github every 10 mins.
The main config is config.json. The module-specific config for the semester lies inside the semester directory (thought it can be changed in the root config file), with the following structure:
- <module_code>
config.json: configuration for organisation name and current AB leveldata.csv: contains the tutor-student mapping for this module- Try to avoid whitespaces for all fields;
- For students with more than one supervisors, please separate the GitHub usernames of the supervisors by comma, such as
"louis,neil". Notice that you need to surround it with double quotation marks to escape the comma; - As shown in
data.sample.csv, use multiple columns if you want to add multiple labels.
Validator provides two points of entries for interacting with Github PRs, doBlock and filterBlock as well a customised subset of Github CRUD operations for dealing with PR.
Blacklist, Whitelist and Greylist composes of Validator to perform specialised operations. Blacklist closes all PR in given repositories. Whitelist closes PRs when conditions are met while Greylist does the same but with more lax conditions. The three classes have been delibrately separated to highlight their customised functionalities i.e. conditions to close, comments and labelling.
Since we are assigning permission for the PR Bot for each individual repository separately, it's good to check that the bot has all the required permissions for every relevant repositories before deployment.
To check that the bot has enough permissions:
npm run checkPermissions
Make sure that ALL the tutors are added to the organisation as members.
When a label does not exist yet inside a repository, and there are multiple concurrent requests trying to add that label to a PR, duplicate labels might get created (This is an issue with Github). Therefore, a safe strategy is to pre-populate all the labels that we need in each repository.
To do that, run npm run addLabels
The bot requires the following in the production environment:
- Node.js v10.0.0 or newer installed
- Internet access (in/out on HTTP/HTTPS)
All Node.js dependencies and their version numbers are described in package.json.
You may find more information about contributing to nus-se-pr-bot in the CONTRIBUTING.md file.
To report a bug, create an issue. Ensure that you search for existing issues reported first before making yours. If it is a possible bug with the underlying library Accuser, create an issue there.