Deploy a self-hosted git forge and CI with OpenTofu

Stand up Forgejo with a bundled Forgejo Actions runner on one CPU VM using the validated OpenTofu template forgejo-git-ci. Forgejo Actions runs CI from the same workflow syntax as GitHub Actions. A data volume at /var/lib/forgejo holds repositories, CI artifacts, and the runner's Docker layers.

Prerequisites#

You need:

• A Quake AI account with application credentials
• OpenTofu 1.6.0 or later (installation guide)
• OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An existing SSH key pair in your project. See Add an SSH key.
• git installed on your workstation
• A copy of the forgejo-git-ci template from the template reference page
• Enough project quota for one s1a.medium instance, a 30 GB boot volume, a 40 GB data volume, and one floating IP

Step 1: Configure variables#

Copy terraform.tfvars.example to terraform.tfvars and set:

key_name = "YOUR_KEY_NAME"
# admin_username = "forgejo-admin"
# admin_email    = "[email protected]"
# domain         = "git.example.com"

Leave domain commented out to start on the floating IP over HTTP. Set domain later when you point DNS at the forge and configure TLS. Defaults match the Forgejo Git and CI reference page.

Step 2: Apply the template#

From the template directory, run:

tofu init
tofu plan
tofu apply

Type yes when prompted. Cloud-init installs Docker, starts the forge and runner, creates the admin account, and registers the runner.

When the run finishes, record the outputs:

WEB_URL=$(tofu output -raw web_url)
FORGE_IP=$(tofu output -raw floating_ip)
echo "$WEB_URL"

Step 3: Retrieve the admin password and sign in#

cloud-init takes a few minutes after apply returns. The admin password is written to /root/forgejo-credentials on the instance:

ssh -i YOUR_PRIVATE_KEY_PATH -o StrictHostKeyChecking=accept-new ubuntu@"$FORGE_IP" 'cloud-init status --wait'
ssh -i YOUR_PRIVATE_KEY_PATH ubuntu@"$FORGE_IP" sudo cat /root/forgejo-credentials

Open web_url in your browser and sign in with the admin username and generated password. Rotate the password under Settings > Account, then delete the credentials file:

ssh -i YOUR_PRIVATE_KEY_PATH ubuntu@"$FORGE_IP" sudo rm /root/forgejo-credentials

Step 4: Push a repository with a CI workflow#

Create a private repository named ci-demo in the forge UI. Generate a personal access token with the write:repository scope under Settings > Applications.

On your workstation:

git clone "http://$FORGE_IP/forgejo-admin/ci-demo.git"
cd ci-demo
mkdir -p .forgejo/workflows
cat > .forgejo/workflows/ci.yml <<'YAML'
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: node --version
      - run: echo "CI is running on my own forge"
YAML
git add .forgejo/workflows/ci.yml
git commit -m "Add CI workflow"
git push origin main

Open the Actions tab in the ci-demo repository and confirm the run goes green. If the run stays queued, check Site Administration > Actions > Runners or read runner logs on the instance.

Step 5: Put a domain and TLS in front (optional)#

Set domain in terraform.tfvars, point the DNS A record at floating_ip, run tofu apply again, and terminate TLS with Forgejo ACME or a reverse proxy. See the template reference page for both paths.

Next steps#

• Forgejo Git and CI template
• CI/CD pipelines
• DevOps automation

Clean up#

Run tofu destroy from the project directory when finished. Type yes to confirm. Verify in the Console that the instance, data volume, and floating IP are gone.