A small forge you can rebuild.

Choose the collaboration layer

Forgejo and Gitea are examples of lightweight forge software; plain SSH Git can be enough for a smaller workflow. Match issues, reviews, package storage and identity requirements to the project. Verify current supported versions and licences.

Separate builds from the forge

A CI runner executes project-controlled code and should not hold unrestricted forge or host credentials. Isolate runners, scope tokens and avoid running untrusted jobs on the same privileged account as the repository service.

Protect access and registration

Disable public signup when the service is private. Use individual accounts, strong authentication and carefully scoped deployment keys. Document the SSH port and host key; do not silently train users to ignore host-key warnings.

Back up the complete service

Repositories alone may not include issues, accounts, attachments and configuration. Follow the forge’s consistent backup procedure and test a restore with file permissions and application secrets intact.

A forge recovery checklist

Export the database consistently and preserve repository storage, attachments, large-file storage if enabled, configuration and encryption secrets. Verify a clone over the intended SSH or HTTPS route after restoration. Keep the forge and any CI worker isolated so a build cannot rewrite the service’s own configuration.

Keep deployment rights narrow

A read-only deployment key can be enough for a server that only pulls code. A release automation may need a small additional scope. Prefer independent keys for different machines, record their purpose and remove them when the machine is retired.

Use the smallest collaboration service that fits

For a few private repositories, bare Git over restricted SSH can be sufficient. Forgejo or Gitea adds accounts, pull requests, issues and optional packages at the cost of a database, application updates and more persistent state. Record which features the team will actually use. Budget repository growth, large-file objects, attachments and build artefacts separately; CI compute can exceed the forge itself.

• Choose a canonical HTTPS name and protect its DNS account.
• Decide whether signup is closed, invitation based or moderated.
• Give the forge service an unprivileged identity and durable private storage.

Official documentation: Forgejo container installation

Separate the web, SSH and database paths

Use the upstream configuration for the selected release and pin the intended image version. A TLS reverse proxy should reach the internal web listener; the database should be reachable only by the forge. If Git SSH uses a container port, keep its advertised host and external port consistent with the mapping. Do not replace or accidentally expose the host administrator SSH listener while changing the forge. Close installation/setup access once the initial owner is created.

• Check persistent volume ownership before starting the application.
• Use a database user restricted to the forge database.
• Keep CI runners on a separate trust boundary, especially for untrusted repositories.

Official documentation: Forgejo Docker networking and persistence

Verify clone, push and a denied operation

Create a disposable private repository and test its HTTPS or SSH clone URL from a normal developer account. Commit and push a harmless file, then verify another authorised reader can fetch it. An uninvited account must fail to read the private repository. Check large-file handling and notification email if enabled. For deployment-only machines, test that a read-only key can fetch and cannot push; an authentication success alone does not prove the intended permission boundary.

# Use the disposable repository URL advertised by your forge:
git clone ssh://[email protected]:2222/team/check.git
# In a clone, inspect which remote is configured:
git remote -v

Recover the discussion as well as the repository

Take a consistent application/database backup, repository storage, attachments, LFS data, configuration and required encryption secrets. Follow the installed forge version’s backup procedure; Gitea backup commands are not automatically interchangeable with every Forgejo release. Rebuild in isolation and verify an issue, attachment, login and clone. If push fails after a move, check SSH host/port, key mapping, storage permissions and advertised clone URLs before changing repository permissions globally.

Official documentation: Gitea backup and restore