CareerByteCode
ByteBlogby CareerByteCode

Self-Host a Git Server and CI Runner on a Free VM

What you build: Gitea and its CI runner (act_runner) on one free e2-micro VM; a push runs the tests, a bug turns CI red with the failing test shown, a revert turns it green, and gitea dump backs it al

Self-Host a Git Server and CI Runner on a Free VM

✍️ Translate this blog into Hindi, Tamil or Telugu

GitHub and GitLab are great, but many teams (and learners) want their own Git server: for private code that must stay in-house, for an air-gapped network, or simply to understand how a Git platform and its CI really work. In this lab you run Gitea, a light self-hosted Git server, and its CI runner act_runner on a single free Google Cloud VM. You push code with a workflow file, watch the CI run your tests, push a bug and see CI fail with the exact failing test, revert it to green, and back up the whole server in one file.

Who it is for: DevOps beginners who know basic Git and Linux. Time: about 1 hour. Cost: free. Everything runs on one e2-micro VM in us-east1 (Google Cloud's Always Free tier), deleted at the end.

Every command below was run for real by the CareerByteCode Team on a fresh Google Cloud project, and every output is the real result we got. Commit ids will differ on your machine.

🧪⭐ Recommended by CareerByteCode · ByteLabs project bundleCloud and DevOps Realtime Starterโ‚น499Build the projects →

Part A: a Git server and CI in plain English

Gitea and act_runner in one picture
A git push reaches Gitea; Gitea creates a job; act_runner on the same VM runs it and reports success or failure back on the commit
  • Gitea: a Git server in one program file: repositories, users, pull requests, issues and Gitea Actions (CI with GitHub Actions-style workflow files). Real-life example: your own office library instead of a public one.
  • Workflow file: .gitea/workflows/ci.yml in the repository says when (on every push) and what (the steps to run).
  • Runner (act_runner): a separate program that asks Gitea for jobs, runs them and sends back the logs and the result. Here it runs jobs directly on the VM ("host" mode), so no Docker is needed on the small VM.
  • Commit status: the result Gitea attaches to each commit (success or failure), shown as a green tick or red cross in the web page, and readable with the API.
  • Token: a long secret that lets scripts use the API as a user. Ours is made inside the lab and saved in a file only that user can read.

Before you start

  1. A Google Cloud account (the free trial works) and a project.
  2. Open Cloud Shell (the >_ icon at the top right of the Google Cloud console) and set your project:
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID
gcloud services enable compute.googleapis.com

Part B: the lab

Step 1: a free e2-micro VM

gcloud compute instances create git-ci-lab --zone=us-east1-b --machine-type=e2-micro \
  --image-family=debian-12 --image-project=debian-cloud --boot-disk-size=10GB --boot-disk-type=pd-standard \
  --no-service-account --no-scopes 2>&1 | tail -2
until gcloud compute ssh git-ci-lab --zone=us-east1-b --tunnel-through-iap --command="echo ssh ok" 2>/dev/null | grep -q ok; do sleep 10; done; echo "SSH works"
NAME        ZONE        MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP   STATUS
git-ci-lab  us-east1-b  e2-micro                   10.142.0.11  EXTERNAL_IP  RUNNING
SSH works

From here on: open an interactive SSH session with the VM using the command below (run it in Cloud Shell; or click Compute Engine > VM instances > SSH next to git-ci-lab). Once you see the VM terminal prompt (you@git-ci-lab:~$), run the next boxes there.

gcloud compute ssh git-ci-lab --zone=us-east1-b

On the VM: everything from here to the clean up runs inside the VM in ~/lab277. Create it and go there:

mkdir -p ~/lab277 && cd ~/lab277

Save Gitea's configuration there as ~/lab277/app.ini:

APP_NAME = Team Git
RUN_USER = git
WORK_PATH = /var/lib/gitea

[database]
DB_TYPE = sqlite3
PATH = /var/lib/gitea/data/gitea.db

[server]
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000
ROOT_URL = http://localhost:3000/
DISABLE_SSH = true

[security]
INSTALL_LOCK = true

[service]
DISABLE_REGISTRATION = true

[actions]
ENABLED = true

[log]
LEVEL = warn

HTTP_ADDR = 127.0.0.1 keeps Gitea reachable only from the VM itself (we never open it to the internet in this lab), INSTALL_LOCK = true skips the web installer, DISABLE_REGISTRATION stops strangers signing up, and [actions] ENABLED = true turns on CI.

Step 2: install Gitea

Why: Gitea is one file. It runs as its own git Linux user with its data in /var/lib/gitea and its config in /etc/gitea, like any well-behaved service.

# Install Gitea (one program file) and give it its own Linux user and folders
cd ~/lab277
sudo apt-get update -qq && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git sqlite3 zstd unzip > /dev/null 2>&1 && git --version
sudo curl -fsSL -o /usr/local/bin/gitea https://dl.gitea.com/gitea/1.22.6/gitea-1.22.6-linux-amd64 && sudo chmod +x /usr/local/bin/gitea
gitea --version | cut -d' ' -f1-3
sudo adduser --system --group --disabled-password --shell /bin/bash --home /home/git git > /dev/null
sudo mkdir -p /var/lib/gitea/{custom,data,log} /etc/gitea && sudo chown -R git:git /var/lib/gitea && sudo cp app.ini /etc/gitea/app.ini && sudo chown -R git:git /etc/gitea
grep -E "^\[|DB_TYPE|HTTP_|ENABLED|INSTALL_LOCK|DISABLE_REG" /etc/gitea/app.ini | tr '\n' ' '; echo
git version 2.39.5
Gitea version 1.22.6
[database] DB_TYPE = sqlite3 [server] HTTP_ADDR = 127.0.0.1 HTTP_PORT = 3000 [security] INSTALL_LOCK = true [service] DISABLE_REGISTRATION = true [actions] ENABLED = true [log]

Step 3: run it as a systemd service

Why: systemd starts Gitea at boot and restarts it if it stops. We wait until the API answers.

# Run Gitea as a systemd service, then ask its API for the version
printf '[Unit]\nDescription=Gitea\nAfter=network.target\n[Service]\nUser=git\nGroup=git\nWorkingDirectory=/var/lib/gitea\nExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini\nRestart=always\nEnvironment=HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea\n[Install]\nWantedBy=multi-user.target\n' | sudo tee /etc/systemd/system/gitea.service > /dev/null
sudo systemctl daemon-reload && sudo systemctl enable --now gitea 2>&1 | tail -1
for i in $(seq 1 30); do curl -s localhost:3000/api/v1/version && break; sleep 2; done; echo
systemctl is-active gitea; free -m | awk 'NR==2 {print "memory used:", $3, "MB of", $2}'
Created symlink /etc/systemd/system/multi-user.target.wants/gitea.service โ†’ /etc/systemd/system/gitea.service.
{"version":"1.22.6"}

active
memory used: 461 MB of 969
Gitea running
Gitea 1.22.6 installed as its own user and running as a systemd service; about 470 MB of the VM's memory in use

Step 4: an admin user and a repository

Why: gitea admin user create makes the first (admin) user from the command line; generate-access-token makes an API token, saved in ~/.gitea-token with permissions 600. The REST API then creates the calc repository. (The password is random and never shown, because the lab only uses the token; for a real server set a strong password you keep.)

# An admin user and a repository. The admin token lives only on this VM (lab only)
sudo -u git gitea admin user create --config /etc/gitea/app.ini --username devlead --password "$(openssl rand -hex 12)" --email devlead@example.com --admin --must-change-password=false 2>&1 | tail -1
TOKEN=$(sudo -u git gitea admin user generate-access-token --config /etc/gitea/app.ini --username devlead --token-name lab --scopes all --raw 2>/dev/null); echo "$TOKEN" > ~/.gitea-token && chmod 600 ~/.gitea-token && echo "token saved to ~/.gitea-token (${#TOKEN} characters)"
curl -s -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" -d '{"name":"calc","private":false,"default_branch":"main"}' localhost:3000/api/v1/user/repos | python3 -c "import json,sys; d=json.load(sys.stdin); print('repo:', d['full_name'], '| clone:', d['clone_url'])"
New user 'devlead' has been successfully created!
token saved to ~/.gitea-token (40 characters)
repo: devlead/calc | clone: http://localhost:3000/devlead/calc.git

Step 5: a CI runner on the same VM

Why: the runner registers once with a registration token from Gitea, then runs as a systemd service. --labels linux-host:host means "jobs that ask for linux-host run directly on this machine".

# A CI runner (act_runner) on the same VM. It runs jobs directly on the VM ("host" mode, no Docker needed)
sudo curl -fsSL -o /usr/local/bin/act_runner https://dl.gitea.com/act_runner/0.2.11/act_runner-0.2.11-linux-amd64 && sudo chmod +x /usr/local/bin/act_runner
act_runner --version
RTOKEN=$(sudo -u git gitea --config /etc/gitea/app.ini actions generate-runner-token 2>/dev/null | tail -1)
sudo mkdir -p /var/lib/act_runner && sudo chown git:git /var/lib/act_runner
cd /var/lib/act_runner && sudo -u git act_runner register --no-interactive --instance http://localhost:3000 --token "$RTOKEN" --name vm-runner --labels linux-host:host 2>&1 | grep -iE "success|error" | sed 's/^.*level=//' | head -2
printf '[Unit]\nDescription=Gitea act_runner\nAfter=gitea.service\n[Service]\nUser=git\nWorkingDirectory=/var/lib/act_runner\nExecStart=/usr/local/bin/act_runner daemon\nRestart=always\nEnvironment=HOME=/home/git\n[Install]\nWantedBy=multi-user.target\n' | sudo tee /etc/systemd/system/act_runner.service > /dev/null
sudo systemctl daemon-reload && sudo systemctl enable --now act_runner 2>&1 | tail -1; sleep 5; systemctl is-active act_runner
sudo journalctl -u act_runner --no-pager -o cat | grep -m 1 -oE "runner: vm-runner.*declare successfully|declared successfully.*|Starting runner daemon.*" | head -1
act_runner version v0.2.11
debug msg="Successfully pinged the Gitea instance server"
info msg="Runner registered successfully."
Created symlink /etc/systemd/system/multi-user.target.wants/act_runner.service โ†’ /etc/systemd/system/act_runner.service.
active
Starting runner daemon"

Step 6: push code with a workflow, CI runs

Why: the repository holds a tiny shell "product" (calc.sh with an add function), its tests (test.sh) and the workflow. The push itself starts the pipeline; then we ask the API for the commit status. Make the folder first: mkdir -p ~/lab277/demo/.gitea/workflows.

~/lab277/demo/calc.sh:

#!/bin/bash
# calc.sh: add two numbers (the "product" our CI tests)
add() { echo $(( $1 + $2 )); }

~/lab277/demo/.gitea/workflows/ci.yml:

name: ci
on: [push]
jobs:
  test:
    runs-on: linux-host
    steps:
      - name: Get the code
        run: git clone --depth 1 --branch "${GITHUB_REF_NAME}" "http://localhost:3000/${GITHUB_REPOSITORY}.git" code
      - name: Run the tests
        run: cd code && bash test.sh

~/lab277/demo/test.sh:

#!/bin/bash
# test.sh: the tests CI runs on every push
source ./calc.sh
fail=0
check() { if [ "$2" = "$3" ]; then echo "PASS $1"; else echo "FAIL $1: expected $3, got $2"; fail=1; fi; }
check "2 + 3" "$(add 2 3)" 5
check "10 + -4" "$(add 10 -4)" 6
exit $fail
# Push code with a CI workflow (.gitea/workflows/ci.yml). The push itself starts the pipeline
cd ~/lab277 && rm -rf work && cp -r demo work && cd work && git init -q -b main && git config user.email devlead@example.com && git config user.name "Dev Lead"
git add . && git commit -qm "calc: add() with tests and CI" && cat .gitea/workflows/ci.yml
git push -q http://devlead:$(cat ~/.gitea-token)@localhost:3000/devlead/calc.git main 2>&1 | grep -v "^remote" ; echo "pushed $(git rev-parse --short HEAD)"
SHA=$(git rev-parse HEAD); for i in $(seq 1 60); do S=$(curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; print(json.load(sys.stdin).get('state', ''))"); [ "$S" = success ] || [ "$S" = failure ] && break; sleep 3; done
curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; d=json.load(sys.stdin); [print('commit', d['sha'][:7], '|', x['context'], '|', x['status'], '|', x['description']) for x in d['statuses']]"
name: ci
on: [push]
jobs:
  test:
    runs-on: linux-host
    steps:
      - name: Get the code
        run: git clone --depth 1 --branch "${GITHUB_REF_NAME}" "http://localhost:3000/${GITHUB_REPOSITORY}.git" code
      - name: Run the tests
        run: cd code && bash test.sh
pushed 46a4479
commit 46a4479 | ci / test (push) | success | Successful in 0s
CI green
The push starts the workflow; the commit status is success

The commit got ci / test (push) | success. In the browser this is the green tick next to the commit.

Break it: a bug in the code

Someone "refactors" add() and it now subtracts. They push.

🎓⭐ Recommended by CareerByteCode · Live trainingCloud & DevOps Live Cohort Internshipโ‚น2,360See the training →
# Break it: a bug in add() (it subtracts). Push it: the CI run fails and shows which test broke
cd ~/lab277/work && sed -i 's/\$1 + \$2/$1 - $2/' calc.sh && git commit -qam "Refactor add()" && git push -q http://devlead:$(cat ~/.gitea-token)@localhost:3000/devlead/calc.git main 2>&1 | grep -v "^remote"; echo "pushed $(git rev-parse --short HEAD)"
SHA=$(git rev-parse HEAD); for i in $(seq 1 60); do S=$(curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; print(json.load(sys.stdin).get('state', ''))"); [ "$S" = success ] || [ "$S" = failure ] && break; sleep 3; done
curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; d=json.load(sys.stdin); [print('commit', d['sha'][:7], '|', x['context'], '|', x['status'], '|', x['description']) for x in d['statuses']]"
sleep 5; L=$(sudo find /var/lib/gitea/data/actions_log -type f -printf "%T@ %p\n" | sort -n | tail -1 | cut -d" " -f2); sudo zstdcat -f "$L" | grep -aoE "(PASS|FAIL) .*" | head -4
pushed 75c710b
commit 75c710b | ci / test (push) | failure | Failing after 0s
FAIL 2 + 3: expected 5, got -1
FAIL 10 + -4: expected 6, got 14

The commit is marked failure, and the job log (which Gitea stores for every run) shows exactly which tests failed and what they expected. Nobody had to run the tests by hand.

Fix it: revert and push

# Fix it: revert the bad commit and push. The next run is green
cd ~/lab277/work && git revert --no-edit HEAD > /dev/null && git push -q http://devlead:$(cat ~/.gitea-token)@localhost:3000/devlead/calc.git main 2>&1 | grep -v "^remote"; git log --oneline | head -3
SHA=$(git rev-parse HEAD); for i in $(seq 1 60); do S=$(curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; print(json.load(sys.stdin).get('state', ''))"); [ "$S" = success ] || [ "$S" = failure ] && break; sleep 3; done
curl -s -H "Authorization: token $(cat ~/.gitea-token)" "localhost:3000/api/v1/repos/devlead/calc/commits/$SHA/status" | python3 -c "import json,sys; d=json.load(sys.stdin); [print('commit', d['sha'][:7], '|', x['context'], '|', x['status'], '|', x['description']) for x in d['statuses']]"
0f47fd7 Revert "Refactor add()"
75c710b Refactor add()
46a4479 calc: add() with tests and CI
commit 0f47fd7 | ci / test (push) | success | Successful in 0s
CI red then green
The buggy commit fails with the failing tests in the log; git revert brings the next run back to success

git revert adds a new commit that undoes the bug (safe for shared history), and the next CI run is green again.

Step 7: back up the whole server

Why: a self-hosted server is only as good as its backups. gitea dump writes the database, the repositories and the configuration into one zip file. Copy it off the VM (for example to a Cloud Storage bucket) on a schedule.

# Back up the whole server (repositories, users, settings) in one file with gitea dump
cd /tmp && sudo -u git gitea dump --config /etc/gitea/app.ini --file /tmp/gitea-backup.zip > /dev/null 2>&1; ls -lh /tmp/gitea-backup.zip | awk '{print $5, $9}'
sudo unzip -l /tmp/gitea-backup.zip | grep -E "gitea-db.sql|repos/devlead/calc.git/HEAD|app.ini" | awk '{print $4}'
free -m | awk 'NR==2 {print "memory used:", $3, "MB of", $2}'
110K /tmp/gitea-backup.zip
repos/devlead/calc.git/HEAD
gitea-db.sql
app.ini
memory used: 478 MB of 969

POC: prove it works

  • Gitea 1.22.6 runs as a systemd service on a free e2-micro, reachable only from the VM.
  • A user, an API token (kept in a 600 file) and a repository were made from the command line.
  • act_runner registered and runs jobs on the VM itself.
  • A push with a workflow ran the tests: success. A buggy push: failure, with the failing tests in the log. A revert: success again.
  • gitea dump backed up the database, repositories and config in one zip.

Quiz task: check what you learned

  1. Where does the workflow file live? (Answer: .gitea/workflows/ in the repository.)
  2. What decides which runner takes a job? (Answer: the job's runs-on label must match a label the runner registered with (linux-host).)
  3. How do you read a commit's CI result from a script? (Answer: GET /api/v1/repos/<owner>/<repo>/commits/<sha>/status.)
  4. Why bind Gitea to 127.0.0.1 in this lab? (Answer: so it is not open to the internet; for team use, put it behind HTTPS (for example Nginx) and a firewall rule.)
  5. Why is host mode risky for untrusted code? (Answer: jobs run directly on the server; use container mode (Docker) or a separate runner VM for code you do not trust.)

Clean up (delete everything)

Type exit to leave the VM and come back to Cloud Shell, then run this in Cloud Shell:

gcloud compute instances delete git-ci-lab --zone=us-east1-b --quiet 2>&1 | tail -1
echo "git-ci-lab VMs left: $(gcloud compute instances list --filter="name=git-ci-lab" --format="value(name)" | wc -l)"
echo "git-ci-lab disks left: $(gcloud compute disks list --filter="name~^git-ci-lab" --format="value(name)" | wc -l)"
Deleted [https://www.googleapis.com/compute/v1/projects/your-project-id/zones/us-east1-b/instances/git-ci-lab].
git-ci-lab VMs left: 0
git-ci-lab disks left: 0
Clean up
The git-ci-lab VM and its disk are deleted: 0 left

FAQ

Can I open the web page? Yes, without exposing it: gcloud compute ssh git-ci-lab --zone=us-east1-b -- -L 3000:localhost:3000, then open http://localhost:3000 on your computer (in Cloud Shell use Web preview on port 3000). We used the API in this lab, so the web view is not part of our tested steps.

Gitea or GitLab? GitLab self-managed has more features but needs about 4 GB of RAM or more. Gitea runs comfortably in about 0.5 GB, which is why it fits a free VM.

Are Gitea Actions compatible with GitHub Actions? Mostly: same YAML style, and many GitHub actions work. In host mode, actions that need Node.js or Docker may not run; use plain run: steps as here, or a runner with Docker.

How do I add HTTPS and a domain? Put Nginx in front as a reverse proxy with a certificate (our Nginx post shows the reverse proxy part), set ROOT_URL to the HTTPS address, and open only port 443.

How do I make backups automatic? A cron job or systemd timer that runs gitea dump nightly and copies the zip to a bucket with a lifecycle rule (keep 30 days, for example).

Can one runner serve many repositories? Yes: a runner registered with an instance-level token takes jobs from every repository on the server.

Troubleshooting

You seeWhyFix
Commit status stays pendingNo runner with a matching label is onlinesystemctl status act_runner; check runs-on matches the runner's labels
Runner registered failsWrong or expired registration tokenGenerate a new token with gitea actions generate-runner-token
Gitea will not startA wrong path or permission in app.inijournalctl -u gitea; data folders must belong to the git user
404 page not found from an API callThe endpoint does not exist in this Gitea versionCheck the API docs for your version (we used commit statuses)
The VM runs out of memorye2-micro has 1 GBKeep host-mode jobs small, or use e2-small for heavier CI

What next

Prepared by the CareerByteCode Team from our tested lab, with AI help for the write-up.

Read next →Linux Performance Troubleshooting: CPU, Memory and IO⏱ 15 min

⭐ Keep learning with CareerByteCode

Hand-picked to go deeper on this topic
News, guides and updates from the CareerByteCode team
🏅 Expert writer

The CareerByteCode team writes about what is new on careerbytecode.in: courses, labs, exams, events and the community, which is free to join for influencers and content creators in tech.

Get CareerByteCode Team's next blog by email

One email a week when they publish. Add the weekly Best of ByteBlog too. No spam, unsubscribe with one click.

We email you once to confirm. By subscribing you agree to the privacy policy.

💬 Comments (0)

Top · Newest

Sign in to comment

Related blogs

🧪⭐ Recommended by CareerByteCode · ByteLabs project bundleCloud and DevOps Realtime Starterโ‚น499Build the projects →