# How to Generate a Repository from a Template in Gitea

## Overview

When working with template repositories in Gitea, you should **NOT** simply clone the template repository directly. Instead, you need to create a **new repository** from the template, which gives you a fresh repository with all the template's content but with its own independent history.

## The Problem

If you just clone a template repository:
- You're working directly with the template code
- You don't have your own repository
- You can't push changes to your own repo
- The deployment configuration will point to the template repo, not your actual project

## The Solution

Use Gitea's API to generate a new repository from the template.

## Step-by-Step Process

### 1. Create a New Repository from the Template

Use the Gitea API `/repos/{owner}/{repo}/generate` endpoint:

```bash
curl -X POST "https://git.startanaicompany.com/api/v1/repos/StartanAICompany/ai-recruit-site-template/generate" \
  -H "Authorization: token YOUR_GITEA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "your-username",
    "name": "your-new-repo-name",
    "description": "Your project description",
    "private": false,
    "git_content": true,
    "git_hooks": false
  }'
```

**Parameters:**
- `owner`: Your Gitea username (who will own the new repo)
- `name`: The name for your new repository
- `description`: Description of your project
- `private`: Whether the repo should be private (true/false)
- `git_content`: **Must be true** - copies all the files from the template
- `git_hooks`: Whether to copy git hooks (usually false)

**Important:** You must include either `git_content: true`, `git_hooks: true`, or `topics: ["something"]` - otherwise you'll get an error: "must select at least one template item"

### 2. Clone Your New Repository

Once created, clone your new repository (not the template):

```bash
git clone git@git.startanaicompany.com:your-username/your-new-repo-name.git
```

### 3. Configure Your Project

Navigate into your new repository and configure it:

```bash
cd your-new-repo-name

# Update .env file with your project details
cp .env.example .env
nano .env

# Update GITEA_REPO_NAME to match your new repository name
# Example:
# GITEA_USERNAME=your-username
# GITEA_REPO_NAME=your-new-repo-name
```

### 4. Deploy

Now you can run the deployment script, which will correctly use your new repository:

```bash
GITEA_API_TOKEN='your_token' ./deploy-to-apps.sh --register --email your@email.com
```

## Example: Creating RyanAnderssonRecruit

Here's the actual command used to create the RyanAnderssonRecruit repository:

```bash
curl -X POST "https://git.startanaicompany.com/api/v1/repos/StartanAICompany/ai-recruit-site-template/generate" \
  -H "Authorization: token 4fda3793205103bf8c73371342718748d55f4309" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "ryan.andersson",
    "name": "ryananderssonrecruit",
    "description": "RyanAnderssonRecruit - Recruitment site",
    "private": false,
    "git_content": true,
    "git_hooks": false
  }'
```

This created a new repository at:
- **SSH URL:** `git@git.startanaicompany.com:ryan.andersson/ryananderssonrecruit.git`
- **Web URL:** `https://git.startanaicompany.com/ryan.andersson/ryananderssonrecruit`

## Benefits of Using Templates This Way

1. **Clean History:** Your new repo starts with a fresh commit history
2. **Independence:** You can modify your repo without affecting the template
3. **Proper Deployment:** The deployment script will correctly reference your repo, not the template
4. **Easy Updates:** You can still pull updates from the template if needed
5. **Multiple Projects:** Create unlimited projects from the same template

## Troubleshooting

### Error: "must select at least one template item"

You forgot to include `git_content: true` in your API request. The API requires at least one of:
- `git_content: true`
- `git_hooks: true`
- `topics: ["something"]`

### The new repo is empty

Make sure you set `git_content: true` in the API request. This copies all files from the template.

### SSH clone not working

Ensure your SSH key is added to Gitea:
```bash
curl -X POST "https://git.startanaicompany.com/api/v1/user/keys" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My SSH Key","key":"ssh-ed25519 AAAA..."}'
```

## References

- [Gitea Template Repositories Documentation](https://docs.gitea.com/usage/template-repositories)
- [Gitea API Documentation](https://docs.gitea.com/api/1.22/)
- [GitHub's approach to templates](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) (similar concept)

## Summary

**Don't:** Clone the template directly
```bash
# ❌ Wrong approach
git clone git@git.startanaicompany.com:StartanAICompany/ai-recruit-site-template.git
```

**Do:** Create a new repo from the template via API, then clone your new repo
```bash
# ✅ Correct approach
# 1. Create new repo from template (via API)
# 2. Clone YOUR new repo
git clone git@git.startanaicompany.com:your-username/your-new-repo-name.git
```