# Forgejo Collaboration Guide

How dev users collaborate on shared projects via git.clarun.xyz.

## Overview

Forgejo is our self-hosted git server at https://git.clarun.xyz. Dev users get automatic accounts when provisioned via `dev-add.sh`.

## Getting Started

### Your Account

When your account is created, you automatically get:
- **Forgejo username** matching your Unix username
- **SSH access** from both your laptop and the dev server
- **Initial password** in `~/.forgejo-credentials` (change on first login)

### Clone a Repository

```bash
# From the dev server (or laptop with SSH key registered)
git clone forgejo@git.clarun.xyz:owner/repo.git
```

> **Note:** The SSH user is `forgejo`, not `git`.

### Web Interface

Browse repos, manage settings, view history: https://git.clarun.xyz

## Collaboration Models

### Shared Repository (Small Teams)

All collaborators have write access to the same repo.

**Setup:**
1. Repo owner adds collaborators via web UI (Settings → Collaborators)
2. Everyone clones the same repo
3. Use branches for features, merge to main

**Best for:** Trusted teams, internal projects, rapid iteration

### Fork + Pull Request (Open Contribution)

Contributors work on personal forks and submit PRs.

**Setup:**
1. Fork the repo via web UI
2. Clone your fork
3. Push changes to your fork
4. Create Pull Request to upstream

**Best for:** External contributors, code review gates, open source style

## Recommended Workflow

We use **trunk-based development**:

```
main (always deployable)
  │
  ├── feature-branch (short-lived)
  │     └── merge back quickly
  │
  └── another-feature
```

### Daily Workflow

```bash
# Start fresh
git checkout main
git pull

# Create feature branch
git checkout -b add-new-feature

# Make changes, commit often
git add .
git commit -m "Add new feature"

# Push and create PR (or merge directly for small teams)
git push -u origin add-new-feature
```

### Commit Messages

Keep them clear and concise:
- ~70 characters for the summary line
- Reference issue IDs if applicable
- No emojis or marketing language

## Repository Settings

### Creating a New Repo

**Via Web UI:**
1. Click "+" → "New Repository"
2. Choose owner (you or an organization)
3. Set visibility (public/private)

**Via API (admins):**
```bash
TOKEN=$(cat /run/secrets/forgejo-api-token)
curl -X POST "http://localhost:3000/api/v1/user/repos" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "private": false}'
```

### Adding Collaborators

1. Go to repo → Settings → Collaborators
2. Search by username
3. Choose permission level (Read, Write, Admin)

## SSH Configuration

### From Your Laptop

Add to `~/.ssh/config`:
```
Host git.clarun.xyz
    HostName git.clarun.xyz
    User forgejo
    IdentityFile ~/.ssh/id_ed25519
```

Then clone with:
```bash
git clone git.clarun.xyz:owner/repo.git
```

### From the Dev Server

SSH keys are pre-configured. Just clone:
```bash
git clone forgejo@git.clarun.xyz:owner/repo.git
```

## Troubleshooting

### "Permission denied (publickey)"

Your SSH key isn't registered in Forgejo.

**Fix:** 
1. Go to https://git.clarun.xyz/user/settings/keys
2. Add your public key (`cat ~/.ssh/id_ed25519.pub`)

### "Repository not found"

Either the repo doesn't exist or you don't have access.

**Fix:**
- Check the URL spelling
- Ask the repo owner to add you as a collaborator
- For private repos, ensure you're authenticated

### Clone works but push fails

You have read access but not write access.

**Fix:** Ask repo owner to grant Write permission in Collaborators settings.

## Best Practices

1. **Pull before starting work** - Avoid merge conflicts
2. **Small, focused commits** - Easier to review and revert
3. **Use branches** - Keep main deployable
4. **Write good commit messages** - Future you will thank you
5. **Don't commit secrets** - Use environment variables or secret management

## Related Docs

- [Dev Onboarding](dev-onboarding.md) - Full setup guide
- [Forgejo Admin](forgejo-admin.md) - API tokens and admin operations