layered-soul/skills/forgejo-operations/templates/FORGEJO-SETUP.md

Forgejo SSH Setup for Agents

Primary git remote: code.example.org (Forgejo, SSH port 2222).

Each agent host gets its own machine user and SSH key. No shared credentials.

On a new agent host

1. Generate a host-specific SSH key

ssh-keygen -t ed25519 -f ~/.ssh/forgejo-<username> -C "<username>"

Replace <username> with the machine user assigned to this host.

2. Add Forgejo SSH config

Host code.example.org
    HostName code.example.org
    User git
    Port 2222
    IdentityFile ~/.ssh/forgejo-<username>
    IdentitiesOnly yes

3. Have the operator register your public key

Send the output of cat ~/.ssh/forgejo-<username>.pub to the operator. They will register it under your machine user on Forgejo.

4. Verify

ssh -T git@code.example.org
# Expected: "Hi there, <username>! You've successfully authenticated..."

5. Clone or add remote

# Fresh clone
git clone git@code.example.org:owner/<repo>.git

# Add remote to existing checkout
git remote add forgejo git@code.example.org:owner/<repo>.git

Repos

Repo	SSH URL
repo-a	git@code.example.org:owner/repo-a.git
repo-b	git@code.example.org:owner/repo-b.git

Permissions

Host	User	Permissions
host-a	agent-a	write (all repos)
host-b	agent-b	write (all repos)
host-c	agent-c	read (all repos)

Rules

• Never copy or share SSH private keys between hosts.
• Public mirrors are read-only — push to Forgejo only.
• See AGENTS.md for the full permissions table.