# GitHub Template Repository Setup

Code assignment stages create a private GitHub repository for each candidate from a **template repository**. This guide covers how to configure your template repository correctly.

## What is a Template Repository?

Template repositories let users generate new repositories with the same directory structure and files. When a candidate reaches a code assignment stage, Kit uses the GitHub API to create a fresh private copy of your template repository for them.

> **Important:** The source repository **must** be explicitly marked as a template on GitHub. A regular repository cannot be used as a template -- the GitHub API will reject the request.

## How to Mark a Repository as a Template

1. Go to your repository on GitHub
2. Click **Settings** (gear icon in the repository navigation)
3. Under **General**, find the **Template repository** section near the top
4. Check the box labeled **Template repository**
5. Click **Save changes** (the setting takes effect immediately)

Once enabled, GitHub will show a "Template" badge on the repository page.

## Requirements Checklist

| Requirement | Details |
|---|---|
| GitHub App installed | Your organization must have the Kit GitHub App installed and active (Integrations > GitHub) |
| Repository exists | The `org/repo` specified in the stage config must exist on GitHub |
| Marked as template | The repository must have "Template repository" checked in Settings > General |
| App has access | The Kit GitHub App installation must have access to the template repository |
| Organization match | The GitHub App installation must cover the organization where candidate repos will be created |

## Configuring the Template in Kit

1. Go to your **Job Posting > Stages**
2. Select or create a **Code Assignment** stage
3. In the **GitHub Template** field, select a repository from the dropdown or type the `org/repo` name
4. The dropdown only shows repositories already marked as templates -- if your repo does not appear, verify it is marked as a template on GitHub
5. Save the stage configuration

Kit will automatically validate that the repository is a valid template after you save. If there is an issue, a warning will appear on the stage card.

## Best Practices for Template Repositories

- **Include a clear README** with assignment instructions, expectations, and submission guidelines
- **Add a `.gitignore`** appropriate to the language and framework
- **Include starter code** or boilerplate that candidates should build on
- **Keep it minimal** -- only include what candidates need to get started
- **Add CI configuration** (GitHub Actions) if you want automated tests on candidate submissions
- **Do not include secrets**, API keys, or proprietary code

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| Candidate stuck on "Setting Up" spinner | Template repository is not marked as a template | Go to the repo's Settings > General and check "Template repository" |
| "Setup encountered an issue" error | Template repo not found or not a template | Verify the repo exists and is marked as a template, then re-trigger setup |
| Template repo missing from dropdown | Repo is not marked as a template | Mark it as a template in GitHub Settings, then reload the page |
| "GitHub App not installed" warning | No active GitHub connection | Install the Kit GitHub App from Integrations settings |
| "GitHub template repository not set" warning | The `github_template` field is empty | Select a template in the stage configuration |
| Candidate cannot access their repo | GitHub invitation was not sent or accepted | Check the candidate's GitHub username and the repo invitation status |

## Related

- [Process Template Configuration](/docs/process-template-configuration) -- YAML configuration for code assignment stages
- [GitHub's template repository documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)