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
- 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.
- 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.
- 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.
- Configuration File (
app.ini):
- Central INI configuration defining runtime settings, listen ports, public URLs, database connection string (DSN), logging mechanisms, and subsystem toggles.
- 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 schemehttp://orhttps://, domain, and optional port/path) used by Gitea to generate clone links, webhooks, and OAuth callbacks.RUN_USER: The operating system system account (commonlygit) configured inapp.inithat 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_runneris 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_runnerdaemons (e.g.,ubuntu-latest:docker://gitea/runner-images:ubuntu-latestorself-hosted:host) used to match workflowruns-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
Method A: Linux Binary with Systemd (Recommended for Bare Metal / VMs)
- Create
gitSystem User:
sudo useradd -r -m -U -d /var/lib/gitea -s /bin/bash git
- 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
- 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
- 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
- Test HTTPS authentication using curl:
curl -i -u "username:token" https://gitea.example.com/api/v1/user
- Test SSH connectivity with verbose output:
ssh -v -T git@gitea.example.com
- Verify SSH port binding and listening services:
ss -tlnp | grep ssh
Root Cause Identification
- If
ssh -vattempts 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
repositoryread/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_URLin/etc/gitea/app.inidoes 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
- Check
ROOT_URLsetting:
grep 'ROOT_URL' /etc/gitea/app.ini
- 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
- Edit
/etc/gitea/app.ini:
[server]
ROOT_URL = https://gitea.example.com/
- 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;
}
- 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 Gatewaywhen loading Gitea. systemctl status giteareportsfailed (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
- Inspect Gitea systemd logs:
journalctl -u gitea -n 50 --no-pager
- Check if port 3000 is occupied:
ss -tlnp | grep 3000
- 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 refusedindicates PostgreSQL is down or unreachable.
Resolution
- Start the database service:
sudo systemctl start postgresql. - If port 3000 is conflicted, change
HTTP_PORTinapp.inito 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.inior repository settings. - No
act_runnerinstance 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
- Check repository workflow path: Must be
.gitea/workflows/<name>.ymlor.github/workflows/<name>.yml. - Inspect registered runner status in Site Admin -> Actions -> Runners.
- Check
act_runnersystem logs:
journalctl -u act_runner -n 50 --no-pager
Root Cause Identification
- If workflow requests
runs-on: ubuntu-latestbut runner is registered only with labelself-hosted, the job remains queued indefinitely.
Resolution
- Update workflow YAML or modify runner labels in
act_runnerconfiguration (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 registerreturns 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
- Test network connectivity from runner host to Gitea:
curl -i https://gitea.example.com/api/v1/version
- Inspect Docker daemon socket permissions:
ls -l /var/run/docker.sock
Root Cause Identification
- Error
dial tcp: lookup gitea.example.com: no such hostindicates 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
- Inspect webhook delivery logs: Open Repository -> Settings -> Webhooks, select target webhook, and view Recent Deliveries.
- 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
500or TCPconnection timed outpinpoints 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
- Identify filled filesystem mounts:
df -h
- 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/lfspinpoints orphaned or unreferenced LFS objects.
Resolution
- Run built-in administrative garbage collection tasks via Gitea CLI or web UI:
gitea doctor check --config /etc/gitea/app.ini
- 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 deniederrors.
Possible Causes
- Version skew between binary creating
gitea dumparchive and target Gitea binary. - Incorrect file system user ownership on extracted repository data.
Investigation and Diagnosis
- Check process execution ownership:
ls -ld /var/lib/gitea/git/repositories
- Compare binary versions:
gitea --version
Root Cause Identification
- Directory owned by
root:rootinstead ofgit:gitprevents the Gitea daemon from accessing bare repositories.
Resolution
- Ensure Gitea version matches the dump source version before initiating restoration.
- 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.iniis owned bygit:gitwith restricted permissions (0640or0600) to prevent unauthorized users from reading database passwords and secret keys. - Run Gitea under an unprivileged user (
git) with system shell set to/bin/bashor/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/*.ymlworkflow 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) withAuthorizedKeysCommandinstead of Gitea’s built-in Go SSH daemon. act_runnerConcurrency: Tune thecapacitysetting inact_runnerconfig.yamlto 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
- Stop Gitea Service:
sudo systemctl stop gitea
- Extract Dump Archive:
unzip gitea-dump-20261103.zip -d /tmp/gitea-restore
- Restore Database:
sudo -u postgres psql gitea < /tmp/gitea-restore/gitea-db.sql
- 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
- 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
- Install PostgreSQL and create
giteadatabase/user. - Configure
/etc/gitea/app.inito connect to PostgreSQL. - Start
gitea.serviceand verify initialization.
Lab 2: Setting Up act_runner
- Enable Actions in
app.ini. - Obtain registration token via Gitea UI.
- Download
act_runner, register with Gitea, and start daemon. - Commit
.gitea/workflows/test.ymlto trigger pipeline.
Lab 3: Troubleshooting Scenario
- Modify
ROOT_URLinapp.inito[http://127.0.0.1:3000](http://127.0.0.1:3000). - Attempt cloning via external domain to observe link generation failure.
- Diagnose issue using
app.iniinspection 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
- Official Gitea Documentation: docs.gitea.com
- Gitea Actions Overview: docs.gitea.com/usage/actions/overview
- Configuration Cheat Sheet (
app.iniReference): docs.gitea.com/tech-notes/configuration-cheat-sheet - Registering
act_runner: docs.gitea.com/usage/actions/act-runner