claro is a GitHub Classroom CLI for teachers

Overview

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

Requirements

• 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

Usage

Straight workflow

1. Create a Github Classroom assignment with a distinguish repository prefix

   • Example: 2022-01-assignment-01

2. Clone all repositories from a Github Classroom organization with a specific assignment prefix

   • Example: claro clone github-organization 2022-01-assignment-01

   

3. Grade each student's work and write down the feedback in the respective Markdown file

   • Tip: Use your best Markdown editor for this

   

4. Push the grading

   • Example: claro push 2022-01-assignment-01

   

Other commands

Pull students repositories

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

List all repositories which start with a specific prefix

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

Customize commit message, grading filename, grading string

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"

Storing claro's GitHub Personal Access Token in the OS keyring

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

Authenticating with git command line to access repositories on GitHub

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
• 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 to file->new->password keyring; when asked for a name, use: login

      # ------------------------------------------------#
      # 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
      # ------------------------------------------------#

    • 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