Domain 6CI/CD & GitOpsINTERMEDIATE

Self-Hosted Git Service with Gitea: Operational Architecture, Actions CI/CD, and Administration Guide

A comprehensive operational handbook for self-hosting Gitea, configuring SSH/HTTPS access, setting up Gitea Actions CI/CD with act_runner, managing databases, and troubleshooting common failures.

Domain: Domain 6: CI/CD, GitOps & Registry•Updated: 2026-11-03
#linux#sysadmin#gitea#devops#git

1. Overview

Gitea is a lightweight, self-hosted Git service written in Go. It provides a full-featured web interface, code review workflows, issue tracking, package registries, webhooks, and an integrated CI/CD engine called Gitea Actions.

In production Linux environments, Gitea solves the problem of retaining full data ownership and control over software repositories without incurring the heavy resource consumption of platform suites like GitLab CE or relying entirely on third-party SaaS vendors like GitHub.

+-----------------------------------------------------------------------+
|                         Production Architecture                       |
|                                                                       |
|  +------------------+     +-------------------+    +---------------+  |
|  | Developer Workstation  |  | Reverse Proxy     |    | Gitea Server  |  |
|  | (Git / HTTPS / SSH)    |->| (Nginx / Caddy)   |--->| (Port 3000)   |  |
|  +------------------+     +-------------------+    +-------+-------+  |
|                                                            |          |
|         +-----------------------+--------------------------+          |
|         |                       |                          |          |
|  +------v------+       +--------v-------+       +----------v-------+  |
|  | PostgreSQL  |       | APP_DATA_PATH  |       | Gitea Actions    |  |
|  | Database    |       | (/var/lib/gitea|       | (act_runner)     |  |
|  +-------------+       +----------------+       +------------------+  |
+-----------------------------------------------------------------------+

Key Use Cases

  • Self-Hosted Source Code Management: Centralized repository hosting with organizational permissions, branch protection, pull requests, and code reviews.
  • Air-Gapped Infrastructure: Operating behind corporate firewalls or isolated environments where public internet access is prohibited.
  • Embedded / Edge Deployments: Hosting Git services on low-resource virtual machines, single-board computers, or small enterprise servers due to Gitea’s small memory footprint (~100 MB RAM baseline).
  • Automated CI/CD Workflows: Running build, test, and container push pipelines via Gitea Actions natively.

Production Stack Placement

In a typical Site Reliability Engineering (SRE) or DevOps pipeline, Gitea sits alongside:

  • CI/CD Integrations: Jenkins or internal pipelines triggered via webhooks.
  • Container Registries: Harbor or Quay for container image storage.
  • Deployment Targets: Kubernetes clusters, Nomad instances, or bare-metal Linux servers updated via GitOps tools (e.g., ArgoCD, Flux) or Gitea Actions.

Architectural Comparison

Feature Gitea GitLab CE GitHub Enterprise
Resource Footprint Low (~100 MB RAM baseline) High (4 GB+ RAM baseline) High (VCS SaaS / Managed Appliance)
Primary Language Go Ruby / Go Proprietary
CI/CD Engine Gitea Actions (act_runner) GitLab Runner GitHub Actions Runners
Database Support SQLite, PostgreSQL, MySQL/MariaDB PostgreSQL Proprietary Managed DB
Deployment Model Single binary, Container, Systemd Omnibus package, Helm chart Cloud / Appliance

Simple Operational Example

When a developer executes git push origin main over HTTPS or SSH, Gitea receives the objects, updates the bare Git repository stored under the server’s data directory, evaluates branch rules, emits JSON webhooks to connected services (e.g., Discord, Jenkins), and enqueues any matching Gitea Actions workflow tasks to registered act_runner daemons.


2. Architecture and Mental Model

To effectively operate and troubleshoot Gitea, a system administrator must understand its internal components, process boundaries, and data flow.

sequenceDiagram
    autonumber
    actor Developer
    participant Proxy as Reverse Proxy (Nginx)
    participant Gitea as Gitea Server Engine
    participant DB as Database (PostgreSQL)
    participant Disk as APP_DATA_PATH
    participant Runner as act_runner (CI/CD)

    Developer->>Proxy: Git Push (HTTPS/SSH)
    Proxy->>Gitea: Forward Request (HTTP 3000 / SSH Passthrough)
    Gitea->>DB: Validate Auth & Permissions
    DB-->>Gitea: Auth Confirmed
    Gitea->>Disk: Write Git Objects to Bare Repo
    Gitea->>DB: Update Branch & Commit Metadata
    Gitea->>Proxy: HTTP 200 OK / Git Receive-Pack Complete
    Proxy-->>Developer: Push Successful

    opt Async Background Tasks
        Gitea->>Runner: Notify Pending Job (.gitea/workflows)
        Runner->>Gitea: Poll & Claim Job Token
        Runner->>Disk: Fetch Code & Execute Pipeline Steps
        Runner->>Gitea: Report Execution Status & Logs
    end

Core Components

  1. Gitea Server Binary (gitea):
  • Single executable serving the web UI, REST API (/api/v1), Git Smart HTTP service, built-in SSH daemon (or handling OpenSSH authorized key hooks), and the Gitea Actions orchestration engine.
  1. Database Engine:
  • Stores user accounts, permissions, organizational structures, pull request state, issue comments, webhook definitions, and CI execution metadata. SQLite is suitable only for small test installations, whereas PostgreSQL or MariaDB/MySQL is mandatory for multi-user production deployments.
  1. Data Directory (APP_DATA_PATH):
  • Stores raw Git objects in bare repositories, Git LFS (Large File Storage) pointers and objects, user avatars, attachments, package storage, and Gitea Actions workflow artifacts.
  1. Configuration File (app.ini):
  • Central INI configuration defining runtime settings, listen ports, public URLs, database connection string (DSN), logging mechanisms, and subsystem toggles.
  1. Gitea Actions Execution Engine (act_runner):
  • An independent worker process running locally or in a container that polls the Gitea server over HTTP/HTTPS API endpoints to fetch, execute, and report workflow jobs.

3. Core Concepts and Terminology

Understanding the following terms is essential when managing Gitea services:

  • Bare Repository: A Git repository structure containing only Git database objects and tracking metadata without a checked-out working workspace. Gitea stores all hosted code in bare repositories on disk under APP_DATA_PATH/repositories.
  • ROOT_URL: The fully qualified public base URL (including scheme http:// or https://, domain, and optional port/path) used by Gitea to generate clone links, webhooks, and OAuth callbacks.
  • RUN_USER: The operating system system account (commonly git) configured in app.ini that owns Gitea processes and file systems.
  • Git Smart HTTP: The Git transfer protocol operating over standard HTTP/HTTPS POST/GET payloads, allowing operations using standard user credentials or Personal Access Tokens (PATs).
  • **Gitea Actions & act_runner**: The workflow automation subsystem compatible with GitHub Actions syntax. act_runner is the daemon that receives enqueued steps from Gitea and executes them inside isolated Docker containers or on host environments.
  • Runner Labels: Key-value metadata strings assigned to act_runner daemons (e.g., ubuntu-latest:docker://gitea/runner-images:ubuntu-latest or self-hosted:host) used to match workflow runs-on: requirements.
  • Workflow Directory Paths: Gitea scans .gitea/workflows/ as its native workflow location, while supporting .github/workflows/ for compatibility with GitHub repositories.
  • Personal Access Tokens (PAT): Scoped authentication tokens generated per user used in place of passwords for HTTPS operations and REST API requests.
  • Deploy Keys: SSH public keys configured specifically per repository. By default, deploy keys grant read-only clone permissions unless write access is explicitly checked during setup.

4. Installation and Version Management

Prerequisites

  • Operating System: Linux (Ubuntu/Debian, RHEL/Rocky Linux, Arch Linux, Alpine).
  • System Account: Unprivileged user dedicated to running Gitea (e.g., git).
  • Database: PostgreSQL 12+ or MariaDB 10.4+ recommended for production.
  • Git: Git CLI 2.0 or newer installed on the host.

Installation Methods

  1. Create git System User:
sudo useradd -r -m -U -d /var/lib/gitea -s /bin/bash git
  1. Download Binary and Set Permissions:
wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.22.0/gitea-1.22.0-linux-amd64
sudo chmod +x /usr/local/bin/gitea
  1. Create Required Directories:
sudo mkdir -p /etc/gitea /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /etc/gitea /var/lib/gitea
sudo chmod 750 /etc/gitea /var/lib/gitea
  1. Create Systemd Service (/etc/systemd/system/gitea.service):
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target postgresql.service

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

Method B: Docker Compose

version: "3"
services:
  gitea:
    image: gitea/gitea:1.22.0
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea_password
    restart: always
    volumes:
      - ./gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea_password
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

Checking Installed Version

Verify installation using CLI or API:

# Check version via CLI
gitea --version

# Check version via REST API
curl -sS http://localhost:3000/api/v1/version

5. Configuration Files and Directory Structure

Configuration Reference Table

Path / Parameter Category Description
/etc/gitea/app.ini Config Primary system configuration file.
/var/lib/gitea Data Base work directory (GITEA_WORK_DIR).
/var/lib/gitea/data Storage Default APP_DATA_PATH for internal state.
/var/lib/gitea/git/repositories Storage Directory containing bare Git repositories.
/var/lib/gitea/data/lfs Storage Storage path for Git Large File Storage objects.
/var/lib/gitea/log Logs Directory storing Gitea application log files.
ROOT_URL Config Knob Public base URL used for clone URLs and webhooks.
RUN_USER Config Knob Operating system user running the process (e.g., git).
[database] Config Knob Database settings (type, host, credentials).
[actions] Config Knob Subsystem toggle for Gitea Actions.

Sample Production app.ini

APP_NAME = Gitea: Enterprise Git Infrastructure
RUN_USER = git
RUN_MODE = prod
WORK_PATH = /var/lib/gitea

[server]
PROTOCOL = http
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000
ROOT_URL = https://gitea.example.com/
SSH_DOMAIN = gitea.example.com
SSH_PORT = 22
DISABLE_SSH = false
START_SSH_SERVER = false ; Uses system OpenSSH daemon

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gitea
USER = gitea
PASSWD = SecurePassword123!
SCHEMA = public
SSL_MODE = disable

[repository]
ROOT = /var/lib/gitea/git/repositories
DEFAULT_PRIVATE = private

[security]
INSTALL_LOCK = true
SECRET_KEY = GENERATED_RANDOM_SECRET_KEY

[actions]
ENABLED = true

[log]
MODE = console, file
LEVEL = Info
ROOT_PATH = /var/lib/gitea/log

Validating Configuration

Always test configuration syntax before restarting services:

gitea doctor check --config /etc/gitea/app.ini

6. Service Management and Common Operations

Service Control Commands

# Start Gitea service
sudo systemctl start gitea

# Stop Gitea service
sudo systemctl stop gitea

# Restart Gitea service (drops transient HTTP connections, reads updated app.ini)
sudo systemctl restart gitea

# Inspect service status and recent journal output
sudo systemctl status gitea

# Enable Gitea to start at system boot
sudo systemctl enable gitea

Reload vs Restart

  • Restart (systemctl restart gitea): Terminates the running Go process and initializes a fresh instance. Mandatory for all changes made within /etc/gitea/app.ini.
  • Reload (systemctl reload gitea): Gitea does not currently support full zero-downtime standard POSIX HUP reloads for all subsystems; configuration edits require a full restart.

Port and Process Verification

# Verify process status and listening sockets (HTTP 3000, SSH 22)
ss -tlnp | grep -E '3000|22'

# Inspect running process resource utilization
ps aux | grep gitea

7. Common Administrative Tasks and Workflows

Task 1: CLI User Creation and Password Resets

When creating an initial site administrator or recovering access:

# List existing users
gitea admin user list --config /etc/gitea/app.ini

# Create a new administrator account
gitea admin user create \
  --config /etc/gitea/app.ini \
  --admin \
  --username sysadmin \
  --password 'ComplexPassphrase123!' \
  --email sysadmin@example.com

# Change an existing user password
gitea admin user change-password \
  --config /etc/gitea/app.ini \
  --username alice \
  --password 'NewSecurePassword456!'

Task 2: Setting Up Gitea Actions and Registering act_runner

Step 1: Enable Actions in Gitea

In /etc/gitea/app.ini, ensure the Actions subsystem is enabled:

[actions]
ENABLED = true

Restart Gitea: sudo systemctl restart gitea.

Step 2: Obtain Registration Token

Navigate in the UI to Site Administration -> Actions -> Runners and click Create new Runner to copy the token. Alternatively, generate a token via CLI:

gitea --config /etc/gitea/app.ini actions generate-runner-token

Step 3: Download and Register act_runner

On the dedicated build host:

# Download binary
wget -O act_runner https://dl.gitea.com/act_runner/0.2.6/act_runner-0.2.6-linux-amd64
chmod +x act_runner

# Register interactively or via flags
./act_runner register \
  --instance https://gitea.example.com \
  --token <REGISTRATION_TOKEN> \
  --name build-runner-01 \
  --labels "ubuntu-latest:docker://gitea/runner-images:ubuntu-latest" \
  --no-interactive

# Run daemon process
./act_runner daemon

Step 4: Add Sample Workflow (.gitea/workflows/ci.yml)

name: Production CI Pipeline
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Run Unit Tests
        run: make test

8. CLI Command Reference and Cheatsheet

Administration & Operations Commands

Command Purpose Key Flags / Arguments Example Explanation
gitea admin user list List registered accounts --config gitea admin user list -c /etc/gitea/app.ini Lists user IDs, names, emails, and admin status.
gitea admin user create Create new account --admin, --username, --password, --email gitea admin user create --admin --username devops --password 'Pass!' --email d@ex.com Provision site admins via automated setup scripts.
gitea doctor check System diagnostics --config, --list gitea doctor check --config /etc/gitea/app.ini Validates directory permissions, database consistency, and configuration sanity.
gitea dump Full backup creation -c, --file, --tempdir gitea dump -c /etc/gitea/app.ini Compresses database SQL, Git repos, LFS, and app.ini into a zip archive.
./act_runner register Register CI runner --instance, --token, --name, --labels ./act_runner register --instance [https://gitea.ex.com](https://gitea.ex.com) --token XYZ Pairs an execution agent with a Gitea instance.
./act_runner daemon Start CI runner daemon --config ./act_runner daemon Runs worker process polling Gitea for jobs.

9. Logs, Monitoring and Diagnostics

Log Locations and Inspection

  • Systemd Journal Logs:
# Tail Gitea service journal output
journalctl -u gitea -f

# View last 100 log lines without pagination
journalctl -u gitea -n 100 --no-pager
  • Application Files: Located under /var/lib/gitea/log/ (gitea.log, http.log, xorm.log).
  • CI/CD Logs:
  • Worker process logs: journalctl -u act_runner -f.
  • Workflow execution output: Accessible within UI per job run (Repo -> Actions -> Job Run).

Metric and Storage Diagnostics

# Check disk capacity of Gitea data partitions
df -h /var/lib/gitea

# Measure breakdown of data directory usage
du -sh /var/lib/gitea/* 2>/dev/null | sort -h

# Query API endpoint for version information
curl -sS https://gitea.example.com/api/v1/version

# Query API using a Personal Access Token (PAT)
curl -sS -H "Authorization: token $PAT_TOKEN" https://gitea.example.com/api/v1/user/repos

10. Troubleshooting Guide and Common Failure Scenarios

Problem 1: Cannot Clone or Push over HTTPS or SSH (401 Unauthorized / Permission Denied)

Symptoms

  • Git CLI rejects HTTPS pushes with HTTP 401 Unauthorized.
  • SSH operations return Permission denied (publickey).

Possible Causes

  • HTTPS: Attempting password authentication when account password logins are restricted, or using an invalid/expired Personal Access Token.
  • SSH: User’s SSH public key missing from Gitea profile settings, wrong SSH key selected by SSH agent, SSH daemon running on a non-standard port (e.g., 2222), or attempting write operations using a read-only Deploy Key.

Investigation and Diagnosis

  1. Test HTTPS authentication using curl:
curl -i -u "username:token" https://gitea.example.com/api/v1/user
  1. Test SSH connectivity with verbose output:
ssh -v -T git@gitea.example.com
  1. Verify SSH port binding and listening services:
ss -tlnp | grep ssh

Root Cause Identification

  • If ssh -v attempts connecting to port 22 while Gitea uses port 2222, the SSH client port is mismatched.
  • If curl returns HTTP 401, the provided credential string is invalid.

Resolution

  • HTTPS: Generate a new PAT with repository read/write permissions from Settings -> Applications and use it as the password.
  • SSH: Configure local ~/.ssh/config:
Host gitea.example.com
  HostName gitea.example.com
  User git
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

If using Deploy Keys, check Allow Write Access in repository settings.

Verification

git ls-remote https://gitea.example.com/org/repo.git
ssh -T git@gitea.example.com -p 2222

Prevention

Disable HTTP password authentication in production, force PAT usage, and document custom SSH ports for all team members.


Problem 2: Wrong Clone URLs or Redirect Loops Behind Reverse Proxy

Symptoms

  • UI displays clone URLs with internal IP addresses or HTTP instead of HTTPS (e.g., [http://gitea.example.com:3000/](http://gitea.example.com:3000/)...).
  • Accessing web pages triggers infinite HTTP 301/302 redirects.

Possible Causes

  • ROOT_URL in /etc/gitea/app.ini does not match the external public domain, protocol, or port.
  • Nginx/Caddy is missing proxy headers (Host, X-Forwarded-Proto, X-Forwarded-For).

Investigation and Diagnosis

  1. Check ROOT_URL setting:
grep 'ROOT_URL' /etc/gitea/app.ini
  1. Inspect HTTP headers received by Gitea:
curl -iL https://gitea.example.com

Root Cause Identification

If ROOT_URL is set to http://localhost:3000/, Gitea will emit redirects pointing to localhost when generating responses.

Resolution

  1. Edit /etc/gitea/app.ini:
[server]
ROOT_URL = https://gitea.example.com/
  1. Ensure Nginx configuration includes required proxy parameters:
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
  1. Restart Gitea: sudo systemctl restart gitea.

Verification

Execute git clone using the URL copied from the web UI to ensure proper protocol formatting.

Prevention

Validate ROOT_URL settings during initial deployment and before applying proxy TLS changes.


Problem 3: Gitea Service Fails to Start / Nginx Returns 502 Bad Gateway

Symptoms

  • Web browser displays 502 Bad Gateway when loading Gitea.
  • systemctl status gitea reports failed (Result: exit-code).

Possible Causes

  • Port 3000 is occupied by another local service.
  • PostgreSQL database unreachable (network timeout, invalid credentials, database service down).
  • Invalid syntax or permissions on /etc/gitea/app.ini.

Investigation and Diagnosis

  1. Inspect Gitea systemd logs:
journalctl -u gitea -n 50 --no-pager
  1. Check if port 3000 is occupied:
ss -tlnp | grep 3000
  1. Validate database connectivity manually:
pg_isready -h 127.0.0.1 -p 5432 -U gitea

Root Cause Identification

  • Journal log reads Failed to start database engine: dial tcp 127.0.0.1:5432: connect: connection refused indicates PostgreSQL is down or unreachable.

Resolution

  • Start the database service: sudo systemctl start postgresql.
  • If port 3000 is conflicted, change HTTP_PORT in app.ini to an open port (e.g., 3001) and update proxy settings.

Verification

Confirm Gitea service health and listening socket:

systemctl status gitea
ss -tlnp | grep 3000

Prevention

Add After=postgresql.service to gitea.service unit file to ensure correct service startup order.


Problem 4: Actions Workflow Never Runs / Stuck Queued Indefinitely

Symptoms

  • Workflows committed to repository show a yellow “Queued” status indefinitely.
  • No workflow executions appear under repository Actions tabs.

Possible Causes

  • Actions disabled in app.ini or repository settings.
  • No act_runner instance registered or active.
  • Mismatch between workflow runs-on: label and registered runner labels.
  • Workflow YAML file saved in an invalid directory path.

Investigation and Diagnosis

  1. Check repository workflow path: Must be .gitea/workflows/<name>.yml or .github/workflows/<name>.yml.
  2. Inspect registered runner status in Site Admin -> Actions -> Runners.
  3. Check act_runner system logs:
journalctl -u act_runner -n 50 --no-pager

Root Cause Identification

  • If workflow requests runs-on: ubuntu-latest but runner is registered only with label self-hosted, the job remains queued indefinitely.

Resolution

  • Update workflow YAML or modify runner labels in act_runner configuration (config.yaml) to ensure exact label matching.
  • Restart runner daemon: sudo systemctl restart act_runner.

Verification

Trigger a new git push event and verify the job status transitions to “Running” in the UI.

Prevention

Standardize organization runner labels across repositories.


Problem 5: Runner Offline / Cannot Register with Gitea Instance

Symptoms

  • Executing ./act_runner register returns connection refused or TLS validation failure.
  • Registered runner drops offline in admin panel.

Possible Causes

  • Registration token expired or mistyped.
  • Runner host cannot reach Gitea’s API due to firewall or incorrect network settings.
  • Runner Docker socket inaccessible when running in container mode.

Investigation and Diagnosis

  1. Test network connectivity from runner host to Gitea:
curl -i https://gitea.example.com/api/v1/version
  1. Inspect Docker daemon socket permissions:
ls -l /var/run/docker.sock

Root Cause Identification

  • Error dial tcp: lookup gitea.example.com: no such host indicates DNS resolution failure on runner host.

Resolution

  • Fix DNS settings on runner host or update network firewalls.
  • Re-generate registration token from Gitea Admin UI and re-run registration command.
  • Grant runner user access to Docker daemon: sudo usermod -aG docker act_runner.

Verification

Check runner service status:

journalctl -u act_runner -n 20 --no-pager

Prevention

Use persistent infrastructure monitoring for runner nodes and run runners as dedicated system service units.


Problem 6: Webhook Delivery Failed

Symptoms

  • Integrated CI builds (e.g., Jenkins) or chat alerts (e.g., Discord) fail to trigger on code pushes.

Possible Causes

  • Target webhook URL unreachable from Gitea host (DNS failure, network firewall, wrong HTTP port).
  • Invalid or expired HMAC secret key.
  • Self-signed TLS certificate failure on recipient service.

Investigation and Diagnosis

  1. Inspect webhook delivery logs: Open Repository -> Settings -> Webhooks, select target webhook, and view Recent Deliveries.
  2. Test network egress connection from Gitea node:
curl -i -X POST https://jenkins.example.com/gitea-webhook/

Root Cause Identification

  • Delivery history showing HTTP status 500 or TCP connection timed out pinpoints target server or network firewall failures.

Resolution

  • Adjust target server firewall rules to accept incoming HTTP POST requests from Gitea node IP.
  • Click Test Delivery in Gitea webhook settings to verify payload delivery.

Verification

Verify a green HTTP status code (e.g., 200 or 202) in webhook delivery logs.

Prevention

Configure automated alerts for third-party service outages.


Problem 7: Disk Full / Bare Repositories and LFS Growing Out of Control

Symptoms

  • Git operations fail with fatal: sha1 write error: No space left on device.
  • Gitea service crashes due to database disk write failures.

Possible Causes

  • Unpruned LFS storage objects, unused packages, accumulated build logs, or unpruned bare repository objects filling APP_DATA_PATH.

Investigation and Diagnosis

  1. Identify filled filesystem mounts:
df -h
  1. Analyze directory size breakdown under APP_DATA_PATH:
du -sh /var/lib/gitea/* | sort -h

Root Cause Identification

  • Large usage under /var/lib/gitea/data/lfs pinpoints orphaned or unreferenced LFS objects.

Resolution

  1. Run built-in administrative garbage collection tasks via Gitea CLI or web UI:
gitea doctor check --config /etc/gitea/app.ini
  1. Delete old Actions build artifacts and purge unreferenced Git LFS files via Site Administration -> Maintenance Tasks.

Verification

df -h /var/lib/gitea

Prevention

Implement automated disk alert thresholds and configure artifact retention limits in Actions workflows.


Problem 8: Migration / Dump Restore Failures

Symptoms

  • Restored Gitea instance crashes upon boot or throws database migration errors.
  • Git repositories fail to load with permission denied errors.

Possible Causes

  • Version skew between binary creating gitea dump archive and target Gitea binary.
  • Incorrect file system user ownership on extracted repository data.

Investigation and Diagnosis

  1. Check process execution ownership:
ls -ld /var/lib/gitea/git/repositories
  1. Compare binary versions:
gitea --version

Root Cause Identification

  • Directory owned by root:root instead of git:git prevents the Gitea daemon from accessing bare repositories.

Resolution

  1. Ensure Gitea version matches the dump source version before initiating restoration.
  2. Recursively reset directory permissions:
sudo chown -R git:git /var/lib/gitea
sudo chmod -R 750 /var/lib/gitea

Verification

Restart Gitea and verify repository access:

systemctl restart gitea
journalctl -u gitea -n 50 --no-pager

Prevention

Always test database restores in staging environments using matching binary versions prior to production upgrades.


11. Security and Best Practices

File Permissions & Ownership

  • Ensure /etc/gitea/app.ini is owned by git:git with restricted permissions (0640 or 0600) to prevent unauthorized users from reading database passwords and secret keys.
  • Run Gitea under an unprivileged user (git) with system shell set to /bin/bash or /sbin/nologin.

Authentication and Network Exposure

  • Enforce PAT Usage: Disable password authentication for Git over HTTP/HTTPS.
  • TLS Termination: Always place Gitea behind a reverse proxy (Nginx, Caddy, Traefik) providing valid TLS certificates (Let’s Encrypt / ACME).
  • SSH Hardening: Use OpenSSH container/host integration with public-key-only authentication.

Gitea Actions Secrets

  • Never hardcode secrets in .gitea/workflows/*.yml workflow files.
  • Store sensitive values (SSH keys, registry tokens) in Repository / Organization / Site Settings -> Secrets.

12. Performance and Resource Optimisation

  • Database Selection: Use PostgreSQL or MariaDB/MySQL for production workloads. SQLite introduces global lock contention during concurrent CI/CD operations or multi-developer pushes.
  • SSH Performance: For high-volume repositories, use host OpenSSH (START_SSH_SERVER = false) with AuthorizedKeysCommand instead of Gitea’s built-in Go SSH daemon.
  • act_runner Concurrency: Tune the capacity setting in act_runner config.yaml to match available host CPU/RAM resources.

13. Backup, Recovery and Maintenance

Creating Backups with gitea dump

Run the built-in backup utility as user git:

sudo -u git gitea dump \
  -c /etc/gitea/app.ini \
  --file /var/backups/gitea-dump-$(date +%Y%m%d).zip

The resulting archive contains:

  • Complete SQL database export.
  • Bare Git repositories.
  • LFS objects and user attachments.
  • Server configuration file (app.ini).

Restoration Procedure

  1. Stop Gitea Service:
sudo systemctl stop gitea
  1. Extract Dump Archive:
unzip gitea-dump-20261103.zip -d /tmp/gitea-restore
  1. Restore Database:
sudo -u postgres psql gitea < /tmp/gitea-restore/gitea-db.sql
  1. Restore Storage Directories and Fix Ownership:
cp -r /tmp/gitea-restore/data/* /var/lib/gitea/data/
cp -r /tmp/gitea-restore/repos/* /var/lib/gitea/git/repositories/
chown -R git:git /var/lib/gitea
  1. Start Gitea Service:
sudo systemctl start gitea

14. Automation and Integration

Systemd Timer for Automatic Daily Backups

Create /etc/systemd/system/gitea-backup.service:

[Unit]
Description=Automated Gitea Backup Service

[Service]
Type=oneshot
User=git
ExecStart=/usr/local/bin/gitea dump -c /etc/gitea/app.ini --file /var/backups/gitea/gitea-dump.zip

Create /etc/systemd/system/gitea-backup.timer:

[Unit]
Description=Daily Gitea Backup Timer

[Timer]
OnCalendar=02:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable the timer: sudo systemctl daemon-reload && sudo systemctl enable --now gitea-backup.timer.


15. Practical Labs and Exercises

Lab 1: Installing Gitea and PostgreSQL

  1. Install PostgreSQL and create gitea database/user.
  2. Configure /etc/gitea/app.ini to connect to PostgreSQL.
  3. Start gitea.service and verify initialization.

Lab 2: Setting Up act_runner

  1. Enable Actions in app.ini.
  2. Obtain registration token via Gitea UI.
  3. Download act_runner, register with Gitea, and start daemon.
  4. Commit .gitea/workflows/test.yml to trigger pipeline.

Lab 3: Troubleshooting Scenario

  1. Modify ROOT_URL in app.ini to [http://127.0.0.1:3000](http://127.0.0.1:3000).
  2. Attempt cloning via external domain to observe link generation failure.
  3. Diagnose issue using app.ini inspection and correct setting back to public URL.

16. Quick Reference and Cheat Sheet

Important Configuration Files

File / Path Purpose
/etc/gitea/app.ini Main application configuration file.
/var/lib/gitea/data Persistent application state data root.
/var/lib/gitea/git/repositories Stored bare Git repositories.

Important Log Locations

Log Purpose
journalctl -u gitea Systemd service log stream.
/var/lib/gitea/log/gitea.log General application logs.
journalctl -u act_runner Actions runner execution logs.

Common Administrative Commands

Task Command
Start Service systemctl start gitea
Check Status systemctl status gitea
Doctor Sanity Check gitea doctor check --config /etc/gitea/app.ini
Backup Instance gitea dump -c /etc/gitea/app.ini
Register CI Runner ./act_runner register --instance <URL> --token <TOKEN>

Troubleshooting Quick Reference

Symptom Initial Investigation
HTTP 401 on Push Verify PAT validity or SSH agent key binding.
502 Bad Gateway Run systemctl status gitea and `ss -tlnp
CI Workflows Queued Check runner registration status and runs-on: label alignment.
Disk Usage High Inspect /var/lib/gitea using du -sh * and prune LFS.

Important Ports and Protocols

Port Protocol Purpose
3000 TCP Default HTTP Web UI / API listen port.
22 TCP Default SSH clone port.
2222 TCP Alternative SSH port when using standalone container.

17. Further Reading and References

  1. Official Gitea Documentation: docs.gitea.com
  2. Gitea Actions Overview: docs.gitea.com/usage/actions/overview
  3. Configuration Cheat Sheet (app.ini Reference): docs.gitea.com/tech-notes/configuration-cheat-sheet
  4. Registering act_runner: docs.gitea.com/usage/actions/act-runner