Proposal: Infrastructure Setup Phase

[Mtze]

Proposal: Infrastructure Setup Phase

Motivation

Many courses require external tooling to be set up for students and teams — GitLab groups, Slack channels, Outline spaces, and more. Today, this setup is done manually by instructors, which is time-consuming, error-prone, and doesn't scale. For a course like iPraktikum with 15+ teams, an instructor has to manually create dozens of resources across multiple platforms, invite the right people, and assign the correct permissions.

PROMPT should offer an Infrastructure Setup Phase that automates this process. Given students and teams from preceding phases (e.g., Team Allocation), it creates and configures external resources based on instructor-defined templates.

iPraktikum Example

For each team, the following needs to be set up:

• GitLab: Create a group, grant Developer access to students, Admin access to the team's tutors and course instructors
• Slack: Create a channel {teamName}-internal with all team members and their tutors; create a second channel {teamName}-general with team members only
• Outline: Create a space {teamName}, grant Write access to students, Admin access to tutors and instructors

This is currently done by hand for every team, every semester.

1. Core Concepts

1.1 Provider (Tool Connector)

A Provider represents an external tool (e.g., GitLab, Slack, Discord, Outline, GitHub). Each provider:

• Defines what types of resources it can create (e.g., GitLab can create Groups and Projects, Slack can create Channels)
• Implements a standard interface for creating resources and managing access
• Has its own authentication configuration (API token, OAuth, etc.)
• Provides human-readable setup instructions explaining how to obtain the required credentials (e.g., "Go to GitLab → Settings → Access Tokens → Create a token with api scope"). These instructions are displayed in the UI when configuring the provider, so instructors without deep technical knowledge can set up the integration independently.

1.2 Resource Configuration

A Resource Configuration is an instructor-defined setup task. It specifies:

• Provider: Which tool to use (e.g., GitLab)
• Resource type: What to create (e.g., Group, Channel, Space)
• Target scope: Whether to create one resource per team or per student
• Name template: A configurable name pattern using variables (e.g., {{courseName}}-{{teamName}})
• Permission mapping: What access level each role gets on the created resource

A single provider can have multiple resource configurations — for example, two Slack channels per team with different names and different members.

1.3 Resource Instance

A Resource Instance is an actual created resource, tracked by the phase:

• Links to its configuration and its target (specific team or student)
• Status: pending, in progress, created, failed
• Error details if creation failed
• External reference (URL or ID) for the created resource

1.4 Permission Mapping

Each resource configuration defines permissions per role:

Role	Description
Student	Students in the team (team-scoped) or the individual student (student-scoped)
Tutor	Tutors assigned to the team (from Team Allocation phase)
Instructor	Course lecturers — always get access

Each provider defines its own permission levels (e.g., GitLab: Guest/Reporter/Developer/Maintainer/Owner; Outline: Read/Write/Admin). The permission mapping maps PROMPT roles to provider-specific permission levels.

1.5 Name Templates

Resource names are configured using templates with variables:

• {{courseName}} — course name
• {{semesterTag}} — semester tag
• {{teamName}} — team name (team-scoped resources only)
• {{studentName}} — student name (student-scoped resources only)

Example: {{semesterTag}}-{{teamName}}-docs → ws25-Team1-docs

2. Phase Inputs

The Infrastructure Setup Phase consumes data from preceding phases via the existing data dependency graph:

• Teams (phase-level input from Team Allocation): List of teams with members and tutors
• Team Allocation (participation-level input from Team Allocation): Which student belongs to which team
• Course participants (from core): For student-scoped resources that don't require teams

3. Instructor UI

3.1 Configuration View

• Add/remove providers with guided setup: each provider shows step-by-step instructions on how to obtain and configure the required credentials (API tokens, OAuth apps, webhook URLs, etc.)
• For each provider, define one or more resource configurations:
  • Select resource type, target scope, name template
  • Map permissions per role
• Preview: Show what will be created before execution (e.g., "14 GitLab groups, 28 Slack channels, 14 Outline spaces")

3.2 Execution & Monitoring Overview

• Dashboard showing all resource instances grouped by provider and configuration
• Status per resource: pending, in progress, created, failed
• For failed resources: show the error message and a retry button
• Bulk retry for all failed resources
• Link to the created external resource where available (e.g., URL to the GitLab group)

4. Provider API (Abstract Interface)

The architecture must define a clear, abstract Provider API that makes it easy to add new tools without modifying the core phase logic. Each provider implements this interface:

Provider:
  name              → Display name (e.g., "GitLab")
  resourceTypes     → List of resource types this provider supports
  authConfig        → Schema for required authentication fields
  authHelpText      → Human-readable instructions for obtaining credentials
                      (displayed in the UI during provider setup)

  authenticate(credentials)
    → Validate and establish connection

  createResource(resourceType, name, metadata)
    → Create the resource, return a handle (external ID/URL)

  grantAccess(resourceHandle, userIdentifier, permissionLevel)
    → Grant a user access to the resource

  revokeAccess(resourceHandle, userIdentifier)
    → Remove a user's access

  deleteResource(resourceHandle)
    → Delete the resource

  getResourceStatus(resourceHandle)
    → Check if the resource still exists and is healthy

Key design principles:

• Stateless providers: Providers are pure adapters — all state (what was created, status, errors) is managed by the phase, not by the provider
• Provider registration: New providers are registered with the phase by implementing the interface and providing their resource types, auth schema, and setup instructions
• Idempotent operations: createResource should handle the case where the resource already exists (e.g., from a previous failed run that partially succeeded)
• User identification: Providers need a way to resolve PROMPT users to external identities. This could be done via email, university login, or a configurable mapping field per provider.

5. Error Handling & Resilience

• Each resource creation is independent — a failure in one resource must not block others
• Errors are captured per resource instance with enough detail to diagnose the issue (API error message, HTTP status, etc.)
• Instructors can retry individual failed resources or trigger a bulk retry
• The phase should handle rate limiting from external APIs gracefully (back-off and retry)

6. Provider Implementations

Initial Providers

• GitLab — Groups, Projects
• Slack — Channels
• Outline — Spaces/Collections

Future Providers

• GitHub — Organizations, Repositories, Teams
• Discord — Servers, Channels, Roles
• Confluence — Spaces, Pages
• Notion — Workspaces, Pages, Databases
• Rancher / Kubernetes — Namespaces, Projects, RBAC bindings

Further providers can be added incrementally by implementing the Provider API.