Skip to content
Tool for grading GitHub-based assignments.
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


gradec accumulates score comments on a GitHub commit, and records the final score of the commit. gradec can also provide a commit's CI build, and retrieve the score of a commit at a later time.

gradec is designed to run on a batch of commits to grade. See its usage for more information.


This project uses yarn as a dependency manager and build runner. After cloning the repo, install the project's dependencies and the gradec command globally:

yarn install
yarn install-global

To run gradec, you will neeed to get a GitHub personal access token and export a GRADEC_ACCESS_TOKEN environment variable with the value of that token. Set the variable in your .bashrc or similar if you want to avoid repeating this for every shell instance.


Usage: gradec [options]

  gradec grade  perform assignment grading    [default]
  gradec list   list assignment grade status

  --version          Show version number                              [boolean]
  --ao, --auto-open  Automatically opens links in a browser           [string] [default: "Safari"]
  -c, --commits      (GitHub) commits to grade                        [string] [required]
  -t, --tests        CI tests to grade                                [string] [required]
  -r, --range        Space-separated range of line numbers to grade   [array] [required]
  -h, --help         Show help                                        [boolean]

  gradec grade -c commits.txt -t travis.txt -r 1 20     grade lines 1-20 in `commits.txt' and `travis.txt'
  gradec -c c.txt -t t.txt -r 5 10 -ao "Google Chrome"  grade lines 5-10 in `c.txt' and `t.txt', auto-opening links in Google Chrome
  gradec list -c c.txt -t t.xt -r 5 10                  list grading status of lines 5-10 in `c.txt' and `t.txt'
  gradec list -c c.txt -t t.xt -r 5 10 > grades.txt     write any known grades for assignments on lines 5-10 to `grades.txt'

Score comments

gradec calculates the grade/score of an assignment by accumulating score comments on a commit. Score comments have the (regex) grammar


where only the first capturing group is used in accumultating the total score.

Score comments:

  • +3: nice! (+3 to score)
  • -2: consider... (-2 to score)
  • -1 (-1 to score)

Not score comments:

  • observation... (+0 to score)
  • 3 (+0 to score)
  • - (+0 to score)

Partial grading

gradec has particular behavior for assignments that are in the process of or have been graded:

  1. Assignments that gradec has graded in the past are not included as needing to be graded.
  2. Assignments for which gradec has previously commented a CI tests link tests are not issued a new CI tests link comment.


Please lint, format, and test your code after development. There are no pre-commit hooks, so this is mostly on an honor system.

This project uses tslint, clang-format, and Jasmine as a linter, automated formatter, and test framework, respectively. tslint and jasmine are installed with the project dependencies; clang-format must be installed separately.

yarn format
yarn lint
yarn lint:fix # apply some automated linting fixes
yarn test


There are no formal contribution guidelines for this project.

If you would like to report a bug, ask a question, or request a feature, please open an issue rather than reaching out personally.

If you would like to implement a change, please submit a PR (and optionally open an issue if your change is significant).

You can’t perform that action at this time.