Getting Started

You’ve ordered a managed Forgejo from server.camp - great choice. Forgejo is a lightweight, fast Git platform for your entire software development workflow - from code management and issues to code reviews and your own package registry. This guide is written for development teams at SMBs, freelancers, and organizations who want professional version control and collaboration on their own infrastructure.

GitHub is a solid starting point - but for businesses and teams, there are compelling reasons to run your own Forgejo instance at server.camp:

Who benefits from a self-hosted Forgejo?

A self-hosted Forgejo makes sense as soon as any of these apply: you work with customer data or proprietary code, you don’t want to pay per-user fees, you need to demonstrate GDPR compliance, or you want a lightweight platform with full admin access. Forgejo is especially resource-friendly - ideal if you want a fast, no-frills Git platform without overhead.

After ordering, you’ll receive an email with the link to your Forgejo instance and your credentials. The initial account is the administrator with the username root.

1. Open the link from the email and sign in with the username root and the password we sent you.
2. On your first login you’ll be prompted to change the password - choose a secure, unique one.
3. You can reach the admin area anytime via the profile icon in the top right → “Administration”.

Keep your admin credentials safe

The root account has full access to your instance. Store its credentials securely - ideally in a password manager like Vaultwarden. Also enable two-factor authentication.

Create your own working account

Use the root account for administrative tasks only. For your daily work (commits, pull requests, issues), create a separate personal account. This keeps administrative and content-related activities cleanly separated.

For security reasons, open registration is disabled by default. As an administrator, you create new users yourself:

1. Go to Administration → Identity & access → User Accounts.
2. Click “Create User Account” and set a username, email address, and an initial password.
3. The new user can then sign in and change their password.

Open registration can be enabled on request

If you’d like to allow self-registration, you can use the instance settings in your dashboard to either open registration completely or restrict it to specific email domains (e.g. only @your-company.com).

For daily Git work, SSH key authentication is recommended over passwords:

1. Generate an SSH key (if you don’t have one): ssh-keygen -t ed25519
2. Copy the public key (~/.ssh/id_ed25519.pub)
3. In Forgejo: User Settings → SSH / GPG Keys → Add Key
4. From now on: git clone git@your-forgejo.srv.camp:group/repo.git

Forgejo has a simple structure:

• User — a personal account with its own repositories
• Organization — a shared space for a team, a client, or a project, with its own permission management
• Repository — the actual Git repository (private or public) where your code, issues, pull requests, and wiki live

Organizations are ideal for bundling repositories for a team and granting access rights centrally via teams.

Use the plus icon in the top right to create new content:

• New Repository — set a name, choose visibility (private or public), and optionally initialize a README and .gitignore. The default branch is main.
• New Organization — set a name, then add teams and members.

Manage access through organizations and teams

Create a separate organization for each client or internal area. Within an organization, create teams (e.g. “Developers”, “Reviewers”) and grant their access rights centrally. No need to configure each repository individually — and an external developer who only works on one client only gets access to that organization.

🏢 Internal
   📦 infrastructure (Ansible, Docker configs)
   📦 libraries (reusable modules)
   📦 tools (internal scripts)
🏢 Client-A
   📦 frontend
   📦 backend
   📦 documentation
🏢 Client-B
   📦 ...

First, install Git on your machine.

# Via SSH (recommended)
git clone git@your-forgejo.srv.camp:group/repo.git

# Via HTTPS
git clone https://your-forgejo.srv.camp/group/repo.git

# Stage changed files for the next commit
git add .

# Save changes as a commit
git commit -m "Brief description of what changed"

# Push changes to Forgejo
git push

Branches let you work on features or bug fixes without affecting the main development line:

# Create a new branch and switch to it
git checkout -b feature/new-feature

# Commit changes in the branch
git add .
git commit -m "Implement login page"

# Push branch to Forgejo
git push -u origin feature/new-feature

Short-lived branches are easier to manage

The shorter a branch lives, the easier it is to handle. Work on a feature, open a pull request, review and merge — then delete the branch. This prevents long-running branches from drifting away from the main branch and becoming hard to merge.

Here’s the workflow we recommend for teams:

1. Every change happens on its own branch
2. When development is done, a Pull Request (PR) is created
3. A teammate reviews the code and provides feedback or approval
4. After approval, the branch is merged into the main branch

1. In Forgejo, navigate to your repository → “Pull Requests” tab → “New Pull Request”
2. Select the source branch (your feature branch) and target branch (e.g. main)
3. Add a title and description — what changed and why?
4. Assign a reviewer, optionally link labels and a milestone
5. Click “Create Pull Request”

As a reviewer:

1. Open the pull request → the “Files Changed” tab shows all code modifications
2. Click a line → leave a comment (questions, suggestions, praise)
3. Click the “Review” button in the top right and finish your review with “Approve” (or “Request changes” / “Comment”)
4. The author can then merge the PR

Protect the main branch

Under Repository Settings → Branches → Branch Protection Rules, enable protection for main. This prevents anyone from pushing directly to the main branch — everything must go through a pull request with a review. It prevents accidental errors in production code and enforces a four-eyes principle.

Forgejo includes everything you need to organize tasks right alongside your code:

• Issues — tasks, bugs, or feature requests with a title, description (Markdown), assignment, and due date.
• Labels — categorization (e.g. bug, feature, urgent, backlog).
• Milestones — milestones with a due date to bundle issues for a release or sprint and track progress.
• Projects (Kanban) — a board with columns (e.g. To Do → In Progress → Review → Done) where you drag issues between columns.

Link issues to pull requests

Write Closes #42 in your pull request description to automatically close the related issue once the PR is merged. This keeps code and tasks cleanly connected.

Every repository includes a built-in Wiki for technical documentation:

• Markdown-based
• Standalone Git repository (can be cloned and edited locally)
• Sidebar navigation

Common Wiki content: architecture overview, developer setup guide, deployment process, decision records.

Wiki vs. README

Use the README.md in the repository for a quick overview (What is this project? How do I run it?). Use the Wiki for detailed documentation that goes beyond the repository itself.

Under the “Releases” tab, you can publish versions based on Git tags, add release notes, and attach binaries (e.g. finished builds). Ideal for providing your team or users with clearly defined version states.

Forgejo includes built-in CI/CD via Forgejo Actions. It’s enabled by default and largely compatible with GitHub Actions in syntax. You define workflows as YAML files in the .forgejo/workflows/ directory of your repository (Forgejo also reads .github/workflows/, which makes migrating existing GitHub Actions workflows easier). On a matching event (e.g. a push), the workflow is triggered.

on: [push]

jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v6
      - run: npm ci
      - run: npm test

Runners aren't included — but available as an add-on

Forgejo Actions requires a Forgejo Runner — a system that actually executes the workflow steps. A runner is not included in the hosting by default. At server.camp, however, you can add a runner to your Forgejo as an affordable add-on — we then take care of running and maintaining it for you. Alternatively, you can run your own runner.

Option 1: Book a runner add-on at server.camp

The easiest path is to add a runner directly as an affordable add-on to your Forgejo. It runs in isolation for your instance, and we handle operation and updates. Just contact our support team or check the Forgejo product page.

Option 2: Run your own Forgejo Runner

You can also run a Forgejo Runner yourself on your own server, a developer machine, or a VM. A step-by-step guide is available in the official Forgejo Actions documentation.

Actions is optional

You can use Forgejo fully without Actions to start — repositories, issues, pull requests, and the wiki all work without a runner. When you’re ready for automated testing or deployments, add a runner.

Forgejo includes a built-in package registry that is enabled by default. You can store your own packages and container images directly in Forgejo — no external registry like Docker Hub or npmjs.com required.

Supported formats include:

• Container/OCI (Docker images)
• npm (JavaScript/Node.js)
• PyPI (Python)
• Maven (Java)
• NuGet (.NET)
• Cargo (Rust)
• Composer (PHP)

You’ll find specific usage instructions and the right commands for each package type in the “Packages” tab of your user or organization profile.

Ideal combined with Actions

The package registry really shines together with Forgejo Actions: a workflow builds your package or container image and pushes it straight into your own registry — all on your instance, with no external services.

You can bring existing repositories from other platforms straight into Forgejo. Use the plus icon in the top right → “New Migration” to import repositories from GitHub, GitLab, or Gitea — including issues, pull requests, and wiki, depending on the source. This lets you move your existing projects onto your own instance without detours.

Forgejo supports SSO via OpenID Connect (OIDC) and LDAP. Since you have full admin access, you can set up an authentication source yourself:

1. Go to Administration → Identity & access → Authentication Sources → Add Authentication Source.
2. Choose OAuth2 as the type and OpenID Connect as the provider, then enter the client ID, client secret, and the OpenID Connect Auto Discovery URL (e.g. https://your-idp.example.com/.well-known/openid-configuration) of your identity provider.
3. Optionally, you can have an account created automatically on first SSO login.

As an identity provider, we recommend Authentik from server.camp — your team members sign in with a central account, and onboarding and offboarding are managed centrally.

We help with setup

Connecting an identity provider requires a few values from both systems. If you need help, our support team is happy to assist.

Every user can enable two-factor authentication under User Settings → Security. We recommend 2FA for all users — required especially for the root account and other administrators.

Never store credentials, tokens, or API keys in code. For personal secrets, use a password manager like Vaultwarden. For Forgejo Actions, store secrets via the secrets management in the repository or organization settings, so they’re available in workflows without appearing in code.

Connect Forgejo with Mattermost via webhooks (Repository Settings → Webhooks). New pull requests, issue updates, and push events land automatically in a developer channel.

Connect Forgejo to Authentik via OpenID Connect. Team members sign in with a single central account, and onboarding and offboarding are managed centrally.

Store Forgejo credentials, access tokens, and SSH keys securely in Vaultwarden.

Tip: Use Issues not just for code tasks, but also as a to-do list for projects. Keep tasks, code, and documentation in one place.

If you’d like to book a runner as an add-on, have questions about permission management, or want to set up SSO — reach out anytime at support@server.camp. We’re happy to help.

You can also find common Forgejo questions on our Forgejo product page. The complete technical documentation is available in the official Forgejo documentation.