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

✍️ 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: 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.ymlin 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 (
successorfailure), 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
- A Google Cloud account (the free trial works) and a project.
- 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.comPart 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 worksFrom 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-bOn the VM: everything from here to the clean up runs inside the VM in ~/lab277. Create it and go there:
mkdir -p ~/lab277 && cd ~/lab277Save 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 = warnHTTP_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' ' '; echogit 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
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.gitStep 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 -1act_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
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.
# 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 -4pushed 75c710b
commit 75c710b | ci / test (push) | failure | Failing after 0s
FAIL 2 + 3: expected 5, got -1
FAIL 10 + -4: expected 6, got 14The 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
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 969POC: 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:successagain. gitea dumpbacked up the database, repositories and config in one zip.
Quiz task: check what you learned
- Where does the workflow file live? (Answer:
.gitea/workflows/in the repository.) - What decides which runner takes a job? (Answer: the job's
runs-onlabel must match a label the runner registered with (linux-host).) - How do you read a commit's CI result from a script? (Answer:
GET /api/v1/repos/<owner>/<repo>/commits/<sha>/status.) - 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.)
- 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
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 see | Why | Fix |
|---|---|---|
Commit status stays pending | No runner with a matching label is online | systemctl status act_runner; check runs-on matches the runner's labels |
Runner registered fails | Wrong or expired registration token | Generate a new token with gitea actions generate-runner-token |
| Gitea will not start | A wrong path or permission in app.ini | journalctl -u gitea; data folders must belong to the git user |
404 page not found from an API call | The endpoint does not exist in this Gitea version | Check the API docs for your version (we used commit statuses) |
| The VM runs out of memory | e2-micro has 1 GB | Keep host-mode jobs small, or use e2-small for heavier CI |
What next
- Git skills for the repositories you host: Git for DevOps: Branches, Merges and Fixing Mistakes.
- Put HTTPS in front of Gitea: Nginx for Beginners: Web Server, Reverse Proxy and HTTPS.
- The managed alternative: Cloud Build Hands-On: Pipelines Without Managing Servers.
- More hands-on posts: ByteBlog. Practice in ByteLabs and see the courses.
Prepared by the CareerByteCode Team from our tested lab, with AI help for the write-up.
⭐ Keep learning with CareerByteCode
Hand-picked to go deeper on this topicGet 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.
Related blogs
CareerByteCode TeamLinux Performance Troubleshooting: CPU, Memory and IO
What you build: a slow e2-micro diagnosed for real: a CPU hog, a memory leak and an OOM kill, a disk flat out, found with top, vmstat, pidstat and iostat and fixed with renice, ionice and kill.
#devops
CareerByteCode TeamLinux Disk and Storage: Mount, Resize and Fix a Full Disk
What you build: a data disk added, mounted and kept in fstab, filled to 100 percent, a deleted-but-open file found, the disk resized live from 10 to 20 GB, and an inode-full disk fixed.
#beginners
CareerByteCode TeamLinux for Cloud Beginners: 50 Commands on a Free VM
What you build: a free e2-micro Linux VM where you practise 50 everyday commands for files, text, permissions, processes, network and packages, in your own Google Cloud account. Every step tested.
#beginners
CareerByteCode TeamGoogle Cloud Free Tier Explained: What Is Really Free
What you build: a tour of the Always Free products (VM, bucket, BigQuery, Cloud Run, Pub/Sub, Secret Manager) with a real price-list cost check, the bigger-VM trap and a budget alert.
💬 Comments (0)
Top · NewestSign in to comment