CHI Repository Setup & Student Onboarding Process

Overview

This document provides a step-by-step guide to setting up a student research repository from a GitHub Repository Template, onboarding a student, and assigning appropriate permissions and organizational teams based on their effort type. Additionally, it outlines the setup of the StudentResearch/MetaProject components for centralized tracking and includes automation scripts for streamlining the process.

GitHub Organizational Structure

CHI Meta-Research activities are managed via GitHub. All activities fall within the GitHub organization. Each separate activity will have its own repository, with one or more associated GitHub project boards. Each individual is made a member of the CHI-CityTech organization, and assigned to a team. The team will contain one or more students, as well as associated faculty mentors (and fellow researchers!). Each team is assigned at least one Project Board, that tracks tasks. The central Repository for Project Management is called "StudentResearch", and contains a Master Project Board that connects all of the activities via student and team issue cards.

1️⃣ Setting Up StudentResearch/MetaProject Components
2️⃣ Setting Up a Repository from a Template
3️⃣ Assigning Student & Organizational Teams

---

1️⃣ Setting Up StudentResearch/MetaProject Components

The StudentResearch repository serves as a central hub for tracking student projects.

Step 1: Create the Meta-Project Board

1. Navigate to StudentResearch → Projects.
2. Click "New Project" and name it CHI Meta-Project Board.
3. Choose Table View for easier organization.
4. Define project columns based on effort type:
   • Culmination
   • Independent Study
   • Internship
   • Research Project
   • Capstone
   • Other

Step 2: Configure the Meta-Project Issue Templates

If not yet set up, create an issue template for Master Student Cards:

1. Navigate to .github/ISSUE_TEMPLATE/.
2. Create master_student_card.yml (or modify an existing one).
3. Ensure the template includes:
   • projects: ["CHI-CityTech/34"] to automatically add issues to the Meta-Project Board.
   • Effort Type dropdown for automated labeling.

Step 3: Prefill the Meta-Project Board with Student Cards

1. Create a Master Student Card for each student using the issue template.
2. Ensure the issue appears in the CHI Meta-Project Board under the correct effort type column.
3. Verify that each card contains:
   • Student name
   • Project repository link
   • Project board link (if applicable)
   • Research focus
   • Weekly check-in section

---

2️⃣ Setting Up a Repository from a Template

Step 1: Create a New Repository from the Template

1. Navigate to the GitHub Repository Template.
2. Click the "Use this template" button.
3. Select "Create a new repository".
4. Name the new repository using the format:

   STUDENT_LASTNAME-PROJECT_NAME
   

   Example:

   Doe-BlendedRealityStudy
   

5. Choose the organization: CHI-CityTech.
6. Set visibility to Private (unless otherwise specified).
7. Click "Create repository".

Step 2: Configure Repository Settings (If Not Automated by Template)

If the repository template does not automate these steps, manually ensure:

1. Enable Issues: Ensure that the Issues tab is enabled.
2. Enable GitHub Projects: If the student will use an individual project board, enable this feature.
3. Set Branch Protection Rules:
   • Navigate to Settings → Branches.
   • Set protection rules on main (e.g., require pull requests for merging).

Step 3: Clone the Repository (Optional)

If working locally:

  git clone https://github.com/CHI-CityTech/STUDENT_LASTNAME-PROJECT_NAME.git
  cd STUDENT_LASTNAME-PROJECT_NAME

3️⃣ Assigning Student & Organizational Teams

Step 1: Add Student to the Repository

1. Navigate to Settings → Manage Access.
2. Click Invite a collaborator.
3. Enter the student's GitHub username.
4. Assign appropriate permissions:
   • Write Access: Allows students to push commits and create issues.
   • Admin Access (only for students managing multiple contributors).

Step 2: Assign Student to an Organizational Team

Organizational teams help manage student access based on effort type.

Effort-Based Teams:

Effort Type	Team Name	Permissions
Culmination	culmination-students	Write
Independent Study	independent-study	Write
Internship	internship-students	Write
Research Project	research-students	Write
Capstone	capstone-students	Write
Other	other-students	Write

1. Navigate to the CHI-CityTech Organization.
2. Click Teams → Select the appropriate team.
3. Click Add a Member.
4. Enter the student’s GitHub username and add them to the team.

---

4️⃣ Automating the Onboarding Process

GitHub Action: Auto-Assign Student Cards to Meta-Project Board

Create this workflow file in:

.github/workflows/assign-to-project.yml

name: "Auto-Assign Student Card to Meta-Project Board"
on:
  issues:
    types: [opened]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - name: Assign Issue to CHI Meta-Project Board
        uses: actions/[email protected]
        with:
          project-url: "https://github.com/orgs/CHI-CityTech/projects/34"
          github-token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}

How This Works

• Triggers when a new Master Student Card issue is created.
• Automatically assigns the issue to the CHI Meta-Project Board.
• Reduces manual steps in organizing students by effort type.

---

5️⃣ Verifying and Testing the Setup

1. Ensure the student accepts the repository invitation.
2. Confirm the student can:
   • Access the repository
   • Create issues & pull requests
   • Submit check-ins
3. Check that the Master Student Card is linked properly to the project.
4. Verify that all student cards are visible in the CHI Meta-Project Board under the correct column.
5. If everything is correct, notify the student that their onboarding is complete.

---

6️⃣ Next Steps

• The student should begin logging their weekly check-ins.
• If any issues arise, they should create an issue in the repository or contact their advisor.
• Regularly review progress via the CHI Meta-Project Board.

Process Validation

To refine this onboarding process, test with a fake student account and adjust where necessary.

---

This document will evolve as we improve the student onboarding workflow. 🚀