ops-jrz1/docs/forgejo-collaboration.md

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

# 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

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

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:

git clone git.clarun.xyz:owner/repo.git

From the Dev Server

SSH keys are pre-configured. Just clone:

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 - Full setup guide
• Forgejo Admin - API tokens and admin operations