stanford-progj-admin

• Overview
• Setup
• Usage
  • Standard workflow
  • Secondary workflow
• Tasks
  • Canvas
  • Invites
  • Repos

Overview

Command-line utilities (using invoke) to help administer Stanford's Programming in Journalism course.

This repo helps manage student repositories generated by cookiecutter-stanford-progj, a cookiecutter template that helps students auto-generate private GitHub repositories for each assignment. The template also automatically invites instructors as collaborators on those repos.

Instructors can use command-line tasks, described below, to manage the large number of repos generated by this type of workflow, which is designed to be a cost-free alternative to paid GitHub team accounts.

The repo provides tasks that help with the following:

• Accessing the Canvas LMS to generate student rosters and downloading student submission links to GitHub repositories.
• Cloning GitHub code repositories based on URLs submitted to Canvas
• Listing and accepting large numbers of collaboration invites
• Searching for and cloning large numbers of student repositories

Setup

Requirements

• git
• Python >= 3.5
• pipenv
• ssh public key added to GitHub
• A personal GitHub API token
• A Canvas LMS API developer key

Install

git clone git@github.com:stanfordjournalism/stanford-progj-admin.git
cd stanford-progj-admin
pipenv install

Add your personal GitHub API token to a project .env file:

# Fill in your own info for below variables
echo GITHUB_API_TOKEN=your_api_token >> .env

If you plan to use the Canvas LMS API, you must add the following environment variables to .env:

# The base URL for your institution's Canvas site
CANVAS_BASE_URL="https://canvas.your-institution.edu"

CANVAS_API_KEY="YOUR_API_KEY"

# This number can be obtained from Canvas using a web browser
CANVAS_COURSE_ID=111111

If you'd like to search for student repos on GitHub based on a standardized search filter, set the REPO_SEARCH_FILTER environment variable. For example:

echo REPO_SEARCH_FILTER=comm-177p >> .env

The above setting is required by the repos.search task when it's not invoked with the --custom-filter option.

Usage

# Activate env
cd stanford-progj-admin
pipenv shell

# See available commands
invoke --list

Standard workflow

The most common workflow involves:

• Accepting student invites to GitHub repositories
• Generating CSVs of GitHub URLs submitted for code assignments
• Cloning student gists and repos for local review and grading

Here is a shell session demonstrating the workflow:

pipenv shell
invoke invites.accept

# Generates data/repos_assignment_1.csv etc.
invoke canvas.assignment-repos

# Clones repos to cloned_repos/assignment_1/{user1,user2,etc.}
invoke repos.clone data/repos_assignment_1.csv

Secondary worfklow

Warning: This workflow does not fully account for possible variations in GitHub project naming conventions.

In the absence of Canvas integration, it's possible to use a more generic GitHub-specific workflow. This involves:

• Accepting repository invites
• Generating a list of GitHub urls to clone (the list may need manual editing since repository names may not always follow standards)
• Cloning repos

pipenv shell
invoke invites.accept

# Search and filter repositories based on a custom filter
invoke repos.search --custom-filter="comm-177p" > data/course_repos.csv

# Clone repos to the cloned_repos/ directory
invoke repos.clone data/course_repos.csv

Tasks

Invites

The invite tasks help manage invitations to student repos on GitHub.

# List all available invites
invoke invites.list

# Accept all available invites
invoke invites.accept

# Interactively choose invites to Accept, Decline or Ignore
invoke invites.accept -i # --interactive

Canvas

The canvas tasks are implemented using the canvasapi library:

canvas.assignment-repos   Generate CSVs containing GitHub URLs for code assignments
canvas.assignments        Display assignment metadata
canvas.roster             show student roster

Repos

The repos tasks help search for and clone student repos on GitHub. The repos.search command conducts a search of repository names on GitHub. It is intended to help generate a text file that lists student repositories. This text file can then be fed to the repos.clone task to assist with cloning student work for grading.

See below for example usage.

# Search for repos based on REPO_SEARCH_FILTER environment variable
invoke repos.search

# Search for repos using a custom filter
invoke repos.search --custom-filter="comm-177p-assignment-1"

# Create a list of repos to clone
invoke repos.search --custom-filter="comm-177p-assignment-1" > assignment_1_repos.txt

# Clone student repos from a file
invoke repos.clone assignment_1_repos.txt