ryananderssonrecruit/how_to_generate_a_repo_from_a_template.md

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:

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):

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:

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:

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:

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:

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
• Gitea API Documentation
• GitHub's approach to templates (similar concept)

Summary

Don't: Clone the template directly

# ❌ 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

# ✅ 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