glabs

README

glabs

Command line tool to manage GitLab repositories for student assignments.

This README is the quick entry point. The full user handbook lives in the docs folder.

Why glabs

• Create assignment repositories for students or groups
• Seed repositories from starter code or custom seeding tools
• Protect branches and set access rules at scale
• Generate URLs, clone repos, and build reports

Installation

Build from source

Prerequisite: Go 1.24+

go install github.com/obcode/glabs/v3@latest

Add glabs to your PATH

After installation, make sure that your Go bin directory is in your PATH so you can use glabs from anywhere:

export PATH="$PATH:$(go env GOPATH)/bin"

You can add this line to your ~/.bashrc, ~/.zshrc, or ~/.profile to make it permanent.

Build from local checkout

go install .

or just unpack the prebuilt binaries

from https://github.com/obcode/glabs/releases

Quickstart

1) Create main config in your home directory

File: ~/.glabs.yaml

gitlab:
  host: https://gitlab.example.org
  token: <personal-access-token>

coursesfilepath: /absolute/path/to/course-configs
courses:
  - mpd
  - vss

2) Create one course file

Example: /absolute/path/to/course-configs/mpd.yaml

mpd:
  coursepath: mpd/semester
  semesterpath: ob-26ss

  blatt01:
    assignmentpath: blatt-01
    per: student
    startercode:
      url: git@gitlab.example.org:mpd/startercode/blatt-01.git
      fromBranch: startercode
      # tag: startercode  # optional: sets this tag in generated repos at startercode commit
      template: true
      templateMessage: Initial Commit

3) Validate config and generate repos

glabs check mpd
glabs generate mpd blatt01

Common commands

glabs check <course>
glabs generate <course> <assignment> [groups...|students...]
glabs protect <course> <assignment> [groups...|students...]
glabs clone <course> <assignment> [groups...|students...]
glabs urls <course> <assignment> [groups...|students...]
glabs report <course> <assignment> [--html|--json]
glabs addgroupguests <course>         # Enable Dependency-Proxy for students

For details on all commands, see docs/commands.md and docs/workflows.md.

User handbook

• Getting started: docs/getting-started.md
• Configuration reference: docs/configuration.md
• Workflows and recipes: docs/workflows.md
• Command reference: docs/commands.md
• Troubleshooting: docs/troubleshooting.md
• Advanced topics: docs/advanced.md

Contributing

Issues and pull requests are welcome.

Testing

Default unit and contract tests:

go test ./...

Integration tests with GitLab Testcontainers (opt-in):

# Group/project lifecycle (createGroup, generateProject, …)
GLABS_RUN_GITLAB_TC=1 go test -tags=integration -v -count=1 ./gitlab/... -run TestIntegration_GitLab_GroupAndProjectLifecycle

# Archive, Delete, ProtectToBranch, Setaccess end-to-end
GLABS_RUN_GITLAB_TC=1 go test -tags=integration -v -count=1 ./gitlab/... -run TestIntegration_GitLab_Operations

# Run all integration tests at once
GLABS_RUN_GITLAB_TC=1 go test -tags=integration -v -count=1 ./gitlab/... -run '^TestIntegration_'

Notes:

• Integration tests are intentionally opt-in because starting GitLab CE in a container takes 5–25 minutes.
• GLABS_RUN_GITLAB_TC means: run GitLab Testcontainer tests.
• Set GLABS_RUN_GITLAB_TC=1 to enable them; without it the tests are skipped automatically.
• Example: GLABS_RUN_GITLAB_TC=0 (or variable unset) keeps integration tests disabled.
• In CI, trigger them via the run_integration workflow dispatch input (dedicated test-integration job).

License

MIT, see LICENSE.