SoC CLI

Supporting globally connected education

View project on GitHub

SoC: GitHub CLI extension for managing the School of Commonwealths

Project Status: Active

Actively used in practice; works reliably, updates are occasional.

A command-line tool designed for educators to manage GitHub organizations for courses in the School of Commonwealths – an innovative model of the education system in which traditional classroom-based activities are transformed into globally connected communication systems (Pierzchalski, 2022). These systems are created by linking academic classes with similar topics between any universities worldwide. The linking is facilitated using GitHub. In the proposed model, students still study in the halls of the universities but additionally use the GitHub service to communicate with each other, involving the review of assignments/tasks analogous to the work of scientists who review each other’s publications. In this way, students develop critical thinking and foster a culture of collaboration. The example data science course material that could be utilized by lecturers from the combined universities can be found on soc-datacience website.

Prerequisites

  1. Find a partner from any university worldwide with whom you would like to combine classroom-based activities into a single communication system. Alternatively, you may run the course on your own — either for a single group of students or by combining several classes into one virtual team.
  2. Create a GitHub account.
    • If you don’t already have one, create a GitHub account: https://github.com/
  3. Create an organization on GitHub.
    • With your GitHub account, create an organization with a Free plan. On your account, choose: Settings ➡ Organizations ➡ New orgranization; or click the link: create your organization
    • Upgrade your organization by clicking the ‘Upgrade to GitHub Team’ button and selecting the organization you want to upgrade. It is good idea to create as many organizations as the number of courses you run. (Note: At least one organization owner is required to have a Pro account and must be verified as a teacher to upgrade an organization for free. You can get a discount for a Pro account by verifying your teacher status here: discount_requests_application)
    • Add your partner to your organization as an ‘Owner’, ensuring that both of you have equal rights and full administrative access to the entire organization (in order for a partner to fully utilize the course management software, they must be assigned the ‘Owner’ role).
  4. Install & set up Git.
    • download and install Git:
      • Linux, Mac: https://www.git-scm.com/downloads
      • Windows: https://gitforwindows.org/
    • configure your name and email, which will be used to identify the author of commits:
    git config --global user.name "Your Name"
git config --global user.email "your_email@example.com" # this is optional
  5. Install & set up GitHub CLI
    • download and install GitHub CLI (gh): https://cli.github.com/
    • log in to GitHub and grant gh additional permissions. When prompted for your preferred protocol for Git operations, select HTTPS, and when asked if you would like to authenticate to Git with your GitHub credentials, enter Y. With that, the GitHub CLI will automatically store your Git credentials for you, so that you don’t have to enter your credentials for every operation requiring authorization.
    gh auth login --scopes admin:org,delete_repo,project

  6. Install the extension to manage the SoC:

    gh extension install pierzcham/gh-soc
  7. Install GitHub App ‘Czujnikownia’.
    • With your GitHub account, install https://github.com/apps/czujnikownia. This app is used to record the times of submitting assignments and reviews to which students have been assigned.
    • Note: Installation of this app is required only for the gh soc log command; other commands will function without it.

Main Commands (illustrated with examples from a Data Science course)

  1. Initialize the course locally in a folder of your choice.

    gh soc init

    The init command creates configuration files user_config.sh, source_config.sh, system_config.sh, and an additional file for student emails named emails.txt. It also creates a folder named ‘logs’ to store JSON data files.

    • Adjust the settings in the user_config.sh file, which already contains default values, to your preferences.
    GH_ORG_NAME='' # insert here your GitHub organization name
GH_TEAM_NAME='SOC-DS'
GH_TEAM_DESCRIPTION='SoC Data Science Course'
GH_TEAM_MEMBERS_EXCLUDED_FROM_REVIEWING=()
TARGET_REPO_DESCRIPTION='SoC Data Science Course'
TARGET_REPOS=(...) # for default values, look in the file
TARGET_PROJECT_TITLE='Monitor-SoC-DS'
    • Add your students’ emails to emails.txt. This file will be used by open command to send invitations to join your GitHub organization ‘GH_ORG_NAME’ and automatically add them to the team ‘GH_TEAM_NAME’.

    Any time you can run a precheck before each use of other commands to make sure your environment is ready to run.

    gh soc precheck

  2. Synchronize the course with the source repositories.

    gh soc sync

    This command creates a GitHub project titled ‘TARGET_PROJECT_TITLE’ from the ‘SOURCE_PROJECT_OWNER’ GitHub account, as specified in source_config.sh. This project is used to gather information on work progress. Subsequently, repositories with names defined in ‘TARGET_REPOS’ array in the user_config.sh file are created based on the template repostories defined in ‘SOURCE_REPOS’ array in the source_config.sh file. If the source repositories are not already templates, it will attempt to convert them. This is useful if you want to use your own repositories as a source and automatically convert them to templates.

    At any time, you can unsynchronize your course from the source repositories by deleting project and all the repositories forked from that source .

    gh soc unsync

  3. Open the course

    gh soc open

    Opening a course involves, in addition to making some necessary organizational settings, creating a ‘GH_TEAM_NAME’ team to which students will be added after they accept the invitations to join the organization sent by the invite command. Team settings are adjusted here to ensure the mechanism for the automatic selection of a reviewer functions properly. Individuals excluded from reviewing, such as teachers, are listed in ‘GH_TEAM_MEMBERS_EXCLUDED_FROM_REVIEWING’. At this stage, task repositories are cloned to a local folder. Next, repositories containing tasks are configured to protect them against modifications by students – the main branch is locked. Students are required to fork the repository to their account in order to make their changes. Finally, the GitHub Pages for the course is enabled and accessible from the web.

    At any time you can close your course.

    gh soc close

    The close command concludes a course by archiving project data and optionally deleting the team associated with the course. When deleting a team, you can optionally remove team members from your organization.

  4. Invite students to join the course

    Sends invitations to students using the email addresses listed in the emails.txt file

    gh soc invite

    The command below deletes the invitations for students based on the email addresses found in the

    emails.txt file.

    gh soc disinvite

  5. Run your course by assigning tasks to your team one at a time.

    gh soc assign <repository name> # e.g. gh soc assign soc-datascience-hello

    At any time, you can unassign the repository from your team.

    gh soc unassign <repository name>

    Moreover, you can save the current state of your team’s progress.

    gh soc log

    The log commnad captures and logs the current state of a specified GitHub project ‘TARGET_PROJECT_TITLE’ into a JSON file for archival or potential analysis purposes.

    Using the status command, you can list the repositories that you have already added to your team.

    gh soc status

  6. If you no longer need the SoC, you can delete it, which entails deleting your GitHub organization.

    gh soc delete

References

Pierzchalski, M. (2022). Szkoła Rzeczypospolitych [Polish version]. In A. B. Kwiatkowska & M. M. Sysło (Eds.), Informatyka w edukacji (pp. 128–138). ISBN 978-83-8180-645-9. Wydawnictwo Adam Marszałek. https://iwe.mat.umk.pl/materials/art2022/16.pdf. English version: The School of Commonwealths. https://doi.org/10.5281/zenodo.18096714