claro is a GitHub Classroom CLI for teachers
claro (classroom) is a cli tool that offers a simple interface that allows the teacher to clone all student repositories at once for grading and then send grades at once to all these repositories.
claro was inspired by the Git-Gud-tool and it was created to make my life simpler as a teacher who relies on Github Classroom. It is suitable for scenarios where the teacher needs to manually grade each assignment and the Github Classroom autograding is not an option.
claro relies on Github's REST API because currently Github Classroom does not offer an API and it has features that are not present in Github Classroom Assistant. The best one: it is a CLI ❤️!
claro provides:
- mass clone of Github repositories
- a template in Markdown for grading (it creates one file per repository)
- customization (commit message, grade sheet title, grading file, etc.)
- access to Github Personal Access Token from operating system keyring (i.e. macOS Keychain, Gnome Keyring), environment var or claro's config file
- git command line application configured properly
git config --global user.email "you@example.com" git config --global user.name "Your Name"
- Git credential store configured properly
- See section below
-
Create a Github Classroom assignment with a distinguish repository prefix
- Example:
2022-01-assignment-01
- Example:
-
Clone all repositories from a Github Classroom organization with a specific assignment prefix
- Example:
claro clone github-organization 2022-01-assignment-01
- Example:
-
Grade each student's work and write down the feedback in the respective Markdown file
- Tip: Use your best Markdown editor for this
-
Push the grading
- Example:
claro push 2022-01-assignment-01
- Example:
claro offers a pull
command suitable for workflows where students make incremental deliveries to the same GitHub Classroom repository.
- Example:
claro pull 2022-01-assignment-01
Before cloning multiple repositories, you might want to check which repositories will be cloned with a specific prefix. claro offers the list
command for that.
- Example:
claro list 2022-01-assignment-01
The claro default strings are:
- Grading filename:
GRADING.md
- It will be created and pushed to student repository
- Grade string:
Grade:
- It will be inside grading file
- Commit message:
Graded project, the file containing the grade is in the root directory
- It is the commit message
- Grade sheet title
Feedback
- It will be inside grading file as title 1 (# Feedback)
You can change the values using claro config
command. The new values will be stored in the claro's config file (default $HOME/.claro.env
).
- Examples:
claro config filename "Correcao.md"
claro config grade "Nota: "
claro config message "Correção finalizada, veja arquivo na raiz do repositório"
claro config title "Comentários"
claro only supports HTTPS remote URL (git over SSH is so annoying).
claro consumes Github's REST API to fetch the list of repositories (assignments) from a GitHub Classroom organization. So, claro uses a GitHub Personal Access Token.
- claro will try to get GitHub Personal Access Token from: (1) operating system keyring; (2) environment var (
GH_TOKEN
); (3) claro's config file (default$HOME/.claro.env
)
You can inform the token whenever you clone repositories, or you can save the token in the operating system keyring (recommended) or in the claro's config file. Please, have a look at Authenticating with git command line to access repositories on GitHub.
- To save the token (claro will try to save to the OS keyring first and then to the config file.)
claro config token add
- To delete the token from OS keyring
claro config token del
Using an HTTPS remote URL has some advantages compared with using SSH. It's easier to set up than SSH, and usually works through strict firewalls and proxies. However, it also prompts you to enter your GitHub credentials every time you pull or push a repository. (GitHub Docs).
To access repositories on GitHub from the command line application over HTTPS you must authenticate with a GitHub personal access token.
You can avoid being prompted for your password (personal access token) by configuring Git to cache your credentials for you on git credential storage. Git works with several credential helper:
- Unsafe and simple way (not recommended!)
- This method stores your password in plaintext on disk, protected only by filesystem permissions (default
$HOME/.git-credentials
) - on Linux, macOS or Windows
git config --global credential.helper store
- The first time git will ask the username and password. Subsequent request will use the credentials from the store (default
$HOME/.git-credentials
).- Example:
https://username:ghp_token@github.com
- Example:
- The first time git will ask the username and password. Subsequent request will use the credentials from the store (default
- This method stores your password in plaintext on disk, protected only by filesystem permissions (default
- Safe with a little complexity
- This method stores your password encrypted on disk in the operating system keyring service.
- You can use native operating system keyring
-
Linux Secret Service dbus interface, which is provided by GNOME Keyring
- Use Seahorse app to create a default collection with
login
name- Open
seahorse
; go tofile->new->password keyring
; when asked for a name, use:login
- Open
# ------------------------------------------------# # on Ubuntu Linux 22.04 LTS # ------------------------------------------------# sudo apt-get install libsecret-1-0 libsecret-1-dev g++ make cd /usr/share/doc/git/contrib/credential/libsecret && sudo make git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret # ------------------------------------------------#
- Use Seahorse app to create a default collection with
-
macOS Keychain (
/usr/bin/security
)git config --global credential.helper osxkeychain
-
- Multi-plataform (Linux, macOS or Windows)
- You can also use a credential helper like Git Credential Manager