# Forgejo Git and CI

Source: https://docs.quake.ai/resources/iac-templates/forgejo-git-ci
Markdown: https://docs.quake.ai/resources/iac-templates/forgejo-git-ci.md

---

# Forgejo Git and CI

This pattern composes Compute, Network, and Block Storage into a self-hosted git forge with a built-in CI runner on infrastructure you control.

## What this template does

Provisions a single instance running [Forgejo](https://forgejo.org) and one Forgejo Actions runner. Forgejo is an open-source git forge, and Forgejo Actions runs CI from the same workflow syntax as GitHub Actions, so existing `.github/workflows` files run with little or no change:

- Compute instance that runs the forge and the runner in Docker, sized so the runner has room to build containers
- Private network, subnet, router, port, and security group; a floating IP for public access
- A block volume mounted at `/var/lib/forgejo`, so repositories, CI artifacts, and the runner's Docker layers live on a volume you can grow rather than on the boot disk
- cloud-init installs Docker, brings up the forge and runner with Docker Compose, creates the admin account, and registers the runner on first boot

No credential ships with this template. The instance generates the admin password and the runner registration token on first boot. The admin password is written to `/root/forgejo-credentials` (readable only by root); retrieve it over SSH and rotate it after first login.

## Forgejo and Gitea

This template uses Forgejo, the community-run fork of Gitea, licensed GPL-3.0-or-later. The forge and the CI runner are open source. Gitea shares the same configuration shape and remains a valid choice: to run it instead, swap the forge image for `docker.gitea.com/gitea` and the runner image for the Gitea runner in `docker-compose.yml`. The variables, ports, and volume layout stay the same.

## Parameters

| Parameter | Description | Default |
| --- | --- | --- |
| `key_name` | SSH keypair name (must already exist) | No default |
| `flavor_name` | Instance size (headroom is for the runner, not the forge) | `s1a.medium` |
| `image_name` | Operating system image | `Ubuntu-24.04` |
| `app_name` | Display name prefix for resources | `forgejo` |
| `admin_username` | Admin account username created on first boot | `forgejo-admin` |
| `admin_email` | Admin account email | `admin@example.com` |
| `domain` | Public domain for the forge; empty uses the floating IP over HTTP | `""` |
| `volume_size` | Block volume size in GiB, mounted at `/var/lib/forgejo` | `40` |
| `git_ssh_port` | Host port forwarded to the forge's in-container SSH | `2222` |
| `external_network` | External network for floating IP allocation | `PublicStatic` |
| `private_cidr` | CIDR for the private subnet | `10.40.0.0/24` |

## Ports and access

| Port | Purpose |
| --- | --- |
| 22 | Host SSH for administration and retrieving the admin password |
| 80 | Forgejo web UI and git over HTTP |
| 443 | Forgejo web UI and git over HTTPS, once you put a domain and TLS in front |
| `git_ssh_port` (default 2222) | git over SSH to the forge |

git over SSH uses a non-22 host port so it does not collide with the host's own SSH daemon. Clone URLs take the shape `ssh://git@HOST:GIT_SSH_PORT/OWNER/REPO.git`; the `git_ssh_clone_example` output prints the exact prefix.

For anything exposed to the internet, set `domain`, point its DNS A record at the floating IP, and terminate TLS with Forgejo's built-in ACME support or a reverse proxy on the host. The README in the template directory covers both paths.

## How CI runs

Forgejo Actions reads workflow files from each repository and dispatches jobs to the registered runner. The bundled runner advertises two labels:

- `docker`: the job runs in a container image (the default is `node:20-bookworm`), suited to most build and test jobs
- `host`: the job runs directly on the runner, for workflows that need the host toolchain

Reference a label in a workflow with `runs-on: docker`. Raise the runner `capacity` in `config.yml` for more concurrent jobs, or add runner instances for more throughput.

## When to use this pattern

Run your own git hosting and CI on a VM you operate, with workflow files that match the GitHub Actions syntax your team already knows. Forgejo maps a push to a pipeline, which makes it a natural companion to the [Coolify host](/resources/iac-templates/coolify-host) for push-to-deploy and the [Next.js app template](/resources/iac-templates/nextjs-app) as a build target.

For a managed build-and-deploy dashboard rather than a git forge, use the [Coolify host template](/resources/iac-templates/coolify-host). For a standalone datastore your CI jobs consume, see [self-managed PostgreSQL](/resources/iac-templates/self-managed-postgres) or the [Redis / Valkey cache](/resources/iac-templates/redis-cache).

## Estimated cost

<PricingCompanion
  components={[
    { kind: "template", slug: "forgejo-git-ci", required: true },
  ]}
/>

## Template source

<TemplateSource slug="forgejo-git-ci" />

<TemplateResourceMap template="forgejo-git-ci" format="opentofu" />

## Customize this pattern

- [Customize a template's image and flavor](/docs/automation/how-to/customize-template-image-flavor)
- [Add a block volume to a template](/docs/automation/how-to/add-volume-to-template)
- [Parameterize a template with a tfvars file](/docs/automation/how-to/parameterize-template-tfvars)

## See also

- [Coolify host template](/resources/iac-templates/coolify-host)
- [Next.js app template](/resources/iac-templates/nextjs-app)