parsertongue.org
Menu

tutorials

Forgejo and Class Maestro basics

Overview

This tutorial introduces the course workflow for using Forgejo repositories created through Class Maestro.

Forgejo is the self-hosted Git service we use for course assignment repositories. If you have used GitHub before, most ideas will feel familiar: repositories, commits, branches, issues, pull requests, and web-based file browsing all work in roughly the same way. The main difference is that your course repositories are created and managed inside the course infrastructure rather than in your personal GitHub account.

Outcomes

After completing this tutorial, you should be comfortable…

  • finding an assignment repository from Class Maestro
  • logging in to Forgejo through Class Maestro
  • registering an SSH key for course Forgejo access
  • cloning a Forgejo repository
  • committing and pushing work back to Forgejo
  • checking that your pushed work appears in the Forgejo web interface
  • reading automated feedback from Forgejo Actions
  • opening an issue when you need help
  • recognizing when to use a pull request workflow

Prerequisites

This tutorial assumes that …

Background

What is Forgejo?

Forgejo is an open source Git server. It plays the same general role as GitHub: it stores a remote copy of your repository, shows your files and commit history in a browser, and provides collaboration tools such as issues, pull requests, and automated checks.

Because Forgejo is open source, organizations can self-host it and customize it for their own workflows. That is what we do for course repositories: the Class Maestro Forgejo instance is customized for assignment work rather than for general purpose project hosting.

In this course, Forgejo is where assignment repositories live. Class Maestro gives you the correct links, provisions repositories when needed, and helps connect course work to course records.

What is Class Maestro?

Class Maestro is the course portal for programming assignment infrastructure. Depending on the assignment, it may show instructions, deadlines, repository links, feedback, or submission status.

For programming assignments, the most important habit is simple:

  1. Start from the assignment page in Class Maestro.
  2. Follow the repository link from Class Maestro to Forgejo.
  3. Clone that exact repository.
  4. Push your completed work back to that same repository using your registered SSH key.
  5. Return to Forgejo or Class Maestro to check that your work arrived.

Do not create a new repository unless the assignment explicitly tells you to do so. In most course workflows, repository creation happens automatically when an assignment is provisioned.

How this differs from GitHub

If you completed the GitHub basics tutorial, the core Git commands are the same:

# download a remote repository to your computer
git clone <repository-url>
# check which files have changed
git status
# stage a file so it will be included in your next commit
git add <filename>
# save the staged change to your local Git history
git commit -m "Describe the change"
# send your committed work back to the remote repository
git push

The important differences are procedural:

  • The repository usually already exists for you.
  • The repository URL comes from Class Maestro or Forgejo, not from github.com/new.
  • You log in through Class Maestro, usually with a magic link sent to your email address.
  • SSH keys are registered in Class Maestro and then associated with your course Forgejo account.
  • As configured, users cannot create arbitrary repositories and repositories are private. Assignment repositories are created during assignment provisioning.
  • Course staff may use Forgejo Issues, Pull Requests, and Actions to review your work.
  • Assignment repositories are private to you, your group when applicable, and the instructional team.

Getting Started

1. Sign in through Class Maestro

Open the course Forgejo login page. If you see multiple sign-in options, choose the Class Maestro login option.

Class Maestro may send you a magic link by email. Open that email and follow the link to finish signing in. The link proves that you control the email address for the account.

2. Register your SSH key

Before cloning with SSH, register your public SSH key in Class Maestro. Class Maestro associates that key with your course Forgejo account.

If you do not already have an SSH key, complete the SSH keys for Git tutorial first.

3. Open the assignment in Class Maestro

Start from the course page in Class Maestro and open the assignment. Look for the link to the repository. It may be labeled something like Repository, Forgejo repository, Starter repository, or Open in Forgejo.

Follow that link. You should land on a Forgejo page for a repository associated with the assignment.

4. Confirm that you are in the correct repository

Before cloning, check the repository page for a few clues:

  • The repository name should match the assignment or project.
  • The repository owner may be your course organization, your username, or your group.
  • The README or assignment files should match the assignment you are trying to complete.

If the repository looks unrelated, stop and ask for help.

5. Copy the SSH clone URL

On the Forgejo repository page, find the clone button or clone URL field.

Forgejo will usually offer both HTTPS and SSH clone URLs. For course work with Class Maestro-managed Forgejo accounts, use the SSH clone URL after registering your SSH key.

The URL will look something like this:

ssh://git@git.hlt.parsertongue.org/course/assignment-repo.git

Copy the URL from your actual assignment repository rather than retyping it from memory.

6. Clone the repository

In your terminal, move to the directory where you keep course repositories. For example:

mkdir -p ~/repos
cd ~/repos

Then clone the repository using the URL you copied from Forgejo:

git clone <repository-url>

After cloning, move into the new repository directory:

cd <repository-name>

Check that Git knows about the remote:

git remote -v

You should see a remote named origin pointing to the Forgejo repository.

Completing an Assignment

1. Read the README first

Most assignment repositories include a README.md file. Read it before editing code.

The README may tell you:

  • which files to edit
  • which files not to edit
  • how to run the assignment
  • how to run tests
  • what counts as a complete submission

If there is a mismatch between the README and the course page, ask for clarification.

2. Make small, testable changes

Work in small steps. After each meaningful change, check the status of your repository:

git status

Run any tests or checks described by the assignment. In many LING 529 repositories, most checks will be inside an nbgrader notebook rather than in a separate terminal command. That usually means opening the assignment notebook, running the notebook cells from top to bottom, and reading the feedback from any validation or test cells included in the notebook.

If a notebook check fails, read the error message carefully before changing more code. A small failing change is much easier to debug than ten failing changes mixed together.

3. Stage and commit your work

When you have a meaningful chunk of working progress, stage the files you changed:

git add <filename>

Then commit the staged changes:

git commit -m "Complete first part of assignment"

Use a message that describes what changed. You do not need to write a masterpiece, but updates and stuff will not help you or your instructor understand the history later.

4. Push to Forgejo

Push your commits back to the remote repository:

git push

If Git reports an SSH authentication problem, confirm that you registered your public key in Class Maestro and that you copied the SSH clone URL. The SSH keys for Git tutorial covers the most common setup problems.

After pushing, refresh the Forgejo repository page in your browser. You should see your latest commit near the top of the repository page.

Checking Feedback

Forgejo Actions

Some assignments may run automated checks in Forgejo Actions when you push. These checks might run tests, style checks, packaging checks, or other validation steps.

To inspect them:

  1. Open the repository in Forgejo.
  2. Look for an Actions tab or a status indicator near your latest commit.
  3. Open the most recent run.
  4. Read any failing step logs.

A passing check does not always mean the assignment is perfect, but a failing check is a strong signal that something needs attention.

Commit history

The repository page should show your recent commits. You can also check from the terminal:

git log --oneline -5

This shows the five most recent commits in your local repository. If you pushed successfully, the same recent commits should appear in Forgejo.

Asking for Help

Issues

If you need help with a repository-specific problem, your instructor may ask you to open a Forgejo Issue.

A useful issue includes:

  • what you were trying to do
  • what command you ran
  • what happened
  • what you expected to happen
  • the relevant error message
  • what you already tried

For example:

I am trying to run the validation cells for Assignment 2.

Where:
The final validation cell in assignment.ipynb

What happened:
The notebook reports ModuleNotFoundError: No module named 'spacy'.

What I expected:
The validation cell should run and report whether my answer passes the check.

What I tried:
I re-ran the setup command from the README and confirmed that I am in the repository directory.

Good issues make it much easier for course staff to help without guessing.

What not to include

Pull Requests

Some course workflows may ask you to submit work through a pull request. A pull request is a request to merge changes from one branch into another branch.

If an assignment asks for a pull request, the basic rhythm is:

git checkout -b assignment-work
# edit files
git add <filename>
git commit -m "Complete assignment work"
git push -u origin assignment-work

Then open Forgejo in your browser and create a pull request from assignment-work into the target branch named in the assignment.

If the assignment does not mention pull requests, you usually only need to push your commits to the expected branch.

Common Problems

I cloned the wrong repository

Return to Class Maestro, open the assignment, and copy the repository link again. Clone the correct repository into a new directory.

Do not copy files into a different repository unless course staff tells you to do so.

git push says authentication failed

Check that you are using the SSH clone URL and that your public key is registered in Class Maestro.

If the course has setup instructions for authentication, follow those exactly. If you are still stuck, open an issue or contact course staff with the exact error message.

git push says the remote contains work you do not have

First, make sure you are in the correct repository:

git remote -v

Then fetch the latest remote information:

git fetch

If the assignment instructions tell you how to update your branch, follow them. If not, ask for help before trying commands that rewrite history.

I committed but Forgejo does not show my work

Check whether you pushed:

git status

If Git says your branch is ahead of origin, your work is committed locally but not yet pushed. Run:

git push

Then refresh the Forgejo page.

I changed a generated file

Some repositories contain generated files, data files, or hidden support files that you should not edit directly. Check the README and git diff:

git diff

If you are unsure whether a changed file belongs in your submission, ask before committing it.

Practice

Before starting a graded assignment, practice the complete loop on a low-stakes repository or setup assignment:

  1. Open the repository from Class Maestro.
  2. Clone it.
  3. Make a small edit to a harmless file such as README.md.
  4. Run git status.
  5. Stage and commit the edit.
  6. Push to Forgejo.
  7. Confirm that the commit appears in the Forgejo web interface.
  8. If Actions run, inspect the result.

Additional Resources