a81fd5f299
Research for ops-jrz1-mh2: how dev users collaborate on git.clarun.xyz Covers: - Account setup and SSH access - Shared repo vs fork+PR models - Trunk-based workflow - Troubleshooting common issues
179 lines
4 KiB
Markdown
179 lines
4 KiB
Markdown
# 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
|