Template for grader image builders for python assignments

• To provide a template for creating a grader image for python assignments
• To automate the programming assignment grading process so that educators can focus more on teaching

1. Fork this repository.
2. Go to the Settings tab of your repository and click on Actions on the left sidebar.
   1. Click on General and go to Workflow permissions.
   2. Choose Read and write permissions and Save.
3. Edit tests/test_syntax.py to set allowed modules and functions.
4. Customize tests/test_results.py to define the expected results.
5. Push to GitHub : build.yml builds your image and pushes to GHCR (GitHub Container Repository).

• script_path fixture will be available if your test script in the tests/ folder imports pytest.
• Currently requirements.txt is for documentation purpose.

• build.yml: Builds and pushes a multi-arch grader image to GHCR.
• Uses GHCR for privacy and GitHub integration—swap to Docker Hub by updating registry and tags if preferred.
• Requires Dockerfile in repo root (see Dockerfile reference). Set BUILDER_PAT in secrets for optional dispatch.

• Builds a lightweight grader image with pytest.
• Installs dependencies from requirements.txt.
• Customize CMD to run your tests (e.g., python3 -m pytest tests/).

This is the grader template — the instructor-facing half of a two-repo pattern:

1. This repo (grader) — you customize the test files, push, and GitHub Actions builds a Docker image containing your tests. The image is published to GHCR.
2. python-homework-template (student-facing) — contains exercise.py and a classroom.yml workflow. When a student pushes, classroom.yml pulls your grader image and runs the tests.

This repo uses secrets.GITHUB_TOKEN (automatically provided by GitHub Actions) to:

• Log in to GHCR and push the grader Docker image
• Pass as GIT_AUTH_TOKEN during Docker build for cloning dependencies

No manual token setup is needed, but you must enable write access:

Settings > Actions > General > Workflow permissions > "Read and write permissions"

Without this, the Docker image push will fail with a 403 error.

After your grader image builds (check the Actions tab), note the image URL:

ghcr.io/{your-username}/{this-repo-name}:latest

In the student homework repository, set this as a repository variable:

Settings > Secrets and variables > Actions > Variables

Variable name: PYTHON_GRADER_??? (replace ??? with the assignment identifier, e.g., PYTHON_GRADER_301) Value: ghcr.io/{your-username}/{this-repo-name}:latest

The following secrets are set on the homework template side (or as organization secrets):

A GitHub fine-grained Personal Access Token that allows the homework repo's workflow to pull the grader image from GHCR.

1. Go to GitHub > Settings (user) > Developer settings > Personal access tokens > Fine-grained tokens.
2. Click Generate new token.
3. Set the following permission:

4. Save as a secret named CR_PAT in the homework repo or organization.

GITHUB_TOKEN cannot be used for this because it is scoped to the current repo and cannot read packages from a different repo.

These power the AI tutor feedback step in the homework repo. At least one must be set.

Specifies the preferred LLM model. If unset, the AI tutor defaults to Gemini or uses whichever single key is available.

• This template is registered as a part of #C-2025-016393 in the Korea Copyright Commission.