GitHub Integration

GitHub Integration

What Is Used

Teambuilder uses the GitHub REST API through the local GitHub manager layer in the server code.

Primary code paths:

• server/services/githubService.ts
• server/integrations/github/GithubManagement.ts
• pages/github.vue
• API routes under server/api/github/ (see the individual route files in that folder)

How It Is Used

Teambuilder uses GitHub for team repository provisioning:

• Connects to GitHub with a Personal Access Token from environment variables.
• Checks whether the app is connected and which GitHub account is active.
• Creates a repository for each team/project when one does not already exist.
• Syncs collaborators by adding student GitHub usernames and removing collaborators that are no longer assigned.

Relevant API actions:

• GET /api/github/status
• POST /api/github/connect
• POST /api/github/disconnect
• POST /api/github/create-repos

Why It Exists

GitHub is used so each team can receive a dedicated repository for collaboration, version control, and project delivery.

This removes manual repository setup and keeps repository membership aligned with the current team assignment data.

What Teambuilder Needs From GitHub

• Repository creation
• Repository existence checks
• Collaborator list management
• Add/remove collaborator operations
• Authenticated username lookup for the connected account

Pages Involved

• pages/github.vue
• pages/teams.vue for team selection context
• pages/students.vue for GitHub username data on students

Data Dependencies

• Student GitHub usernames come from the github field on student records.
• Semester selection controls which teams are processed.
• Team membership is read from the database before repo sync.

Notes

• If GITHUB_TOKEN is missing, GitHub connection fails gracefully.
• Repository names are sanitized from project names before creation.
• The integration is designed to keep collaborators synchronized with the database state.