Gitea

Deploying a self-hosted Git server, configuring SSH key auth, pushing the project, and establishing branch protection.

I created a dedicated VM for Gitea because I didn’t want to mix other services with it. The Git server is its own piece of infrastructure and it needs to be available even if the control node is being rebuilt.

Keeping Git and PostgresSQL off the Ansible control node means Ansible always has full access to CPU and memory when running large parallel playbook executions.

01 VM Specifications

OS:        Ubuntu Server 22.04 LTS
Hostname:  gitea
CPU:       2 vCPU
RAM:       2 GB
Disk:      30 GB
Network:   1 NIC (bridged to management network)

As I did with the control node VM, I also assigned a static IP and added a DNS entry for this VM.

02 System Setup

After the OS installation, I ran system updates and installed Docker Engine and Docker Compose.

1
2

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg

1
2
3

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

1
2

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Next I added my user to the docker group so I can run Docker commands with sudo.

1
2

sudo usermod -aG docker $USER
newgrp docker

Then I verified Docker was running.

1
2

docker version
docker compose version

03 Docker Compose File

I created a directory structure for Gitea’s Docker Compose deployment and created the Compose file. Keeping all Docker service deployments in /opt/ makes things predictable across all VMs.

1
2
3

sudo mkdir -p /opt/gitea
sudo chown $USER:$USER /opt/gitea
cd /opt/gitea

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

version: "3"

services:
  gitea:
    image: gitea/gitea:latest
    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_db_password
    restart: unless-stopped
    volumes:
      - ./data/gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:16
    container_name: gitea-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea_db_password
      - POSTGRES_DB=gitea
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

I created an .env file alongside the Compose file to hold the credentials separately.

1
2
3

POSTGRES_USER=gitea
POSTGRES_PASSWORD=gitea_password
POSTGRES_DB=gitea

Then I updated the Compose file to reference those variables.

1
2
3
4
5
6
7

- GITEA__database__USER=${POSTGRES_USER}
- GITEA__database__PASSWD=${POSTGRES_PASSWORD}
- GITEA__database__NAME=${POSTGRES_DB}

- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
- POSTGRES_DB=${POSTGRES_DB}

Docker Compose automatically reads a .env file in the same directory as the docker-compose.yml file.

04 Deploying Gitea

After creating the compose and .env files, I brought the stack up.

1
2

cd /opt/gitea
docker compose up -d

To check the status, I ran:

1

docker compose ps

NAME        IMAGE               STATUS          PORTS
gitea       gitea/gitea:latest   Up 30 seconds   0.0.0.0:3000->3000/tcp, 0.0.0.0:2222->22/tcp
gitea-db    postgres:16          Up 31 seconds   5432/tcp

If either show ‘Restarting’ or ‘Exited’, I can check the logs:

1
2

docker compose logs gitea
docker compose logs db

05 Initial Configuration

I went to http://gitea:3000 and was presented with the initial configuration page. Most of the database settings should already be populated.

Then clicked on ‘Install Gitea’.

06 SSH Key Authentication

To make it so I can run git push and git pull over SSH without prompting for a password I setup SSH key authentication.

On ansible-ctrl I genereated an ed25519 key pair.

1

ssh-keygen -t ed25519 -C "ansible-ctrl > gitea" -f ~/.ssh/gitea

I started ssh-agent and added the key so the passphrase only needs to be entered once per session

1
2
3
4
5

(.venv) $ eval "$(ssh-agent -s)"
Agent pid 12345
(.venv) $ ssh-add ~/.ssh/gitea
Enter passphrase for /home/nesto/.ssh/gitea:
Identity added: /home/nesto/.ssh/gitea

I set a strong passphrase when prompted since a key without a passphrase is equivalent to a password written on a sticky note.

So I didn’t have to start the ssh-agent manually on every login, I added the following to ~/.bashrc:

# Start ssh-agent if not already running
if [ -z "$SSH_AUTH_SOCK" ]; then
    eval "$(ssh-agent -s)" > /dev/null
    ssh-add ~/.ssh/gitea 2>/dev/null
fi

This will start the agent and load the key on login. The passphrase prompt will appear once, and then all following Git and SSH operations will use the cached key.

Next, I configured SSH to use this specific key when conencting to Gitea:

Host gitea
    HostName      gitea
    Port          2222
    User          git
    IdentityFile  ~/.ssh/gitea

I then set the proper permissions on ansible-ctrl.

1
2
3

chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/gitea
chmod 644 ~/.ssh/gitea.pub

I then copied the public key conent and added it to Gitea.

1

cat ~/.ssh/gitea.pub

I made sure I copied the output, then went to Gitea’s web UI. From there I went to Settings > SSH/GPG Keys > Add Key.

Then verified the SSH connection works:

1

ssh -T git@gitea

Hi there, git! You've successfully authenticated with the key named ansible-ctrl, but Gitea does not provide shell access.

The ‘does not provide shell access’ message is normal since Git hosting platforms don’t offer interactive shells.

07 Creating the Repository

In the Gitea web UI, I clicked the + button in the top right and selected New Repository:

Repository Name:    network-automation-lab
Visibility:         Private
Description:        Ansible network automation
Initialize Repo:    (unchecked)
.gitignore:         None
License:            None
README:             None
Default Branch:     main

Back on ansible-ctrl I added the Gitea repo as a remote and pushed the existing history.

1
2
3

cd ~/network-automation-lab
git remote add origin git@gitea:nesto/network-automation-lab.git
git push -u origin main

I confirmed the push by refreshing the Gitea web UI. The repository should show all the files committed.

08 Branch Protection

I configured branch protection on main to enforce a pull request workflow. Even though I’m the only user right now, this builds the habit of never pushing directly to main.

In the Gitea web UI, I went to Repository Settings > Branches > Add Branch Protection Rule and configured it this way:

Branch Name Pattern:              main
Enable Branch Protection:          Checked
Disable Push:                      Checked
Enable Push Whitelist:             Unchecked
Require Approvals:                 Checked
Required Approvals:                1
Block Merge on Rejected Reviews:   Checked
Block Merge on Outdated Branch:    Checked
Block Merge on Official Review:    Unchecked
Enable Status Checks:              Unchecked (for now)

The daily workflow for making changes will look like this:

1. Create a feature branch from main

1

git checkout -b feat/add-ntp-role

2. Make changes, stage, commit

1
2

git add -A
git commit -m "feat: add NTP configuration role"

3. Push the feature branch to Gitea

1

git push -u origin feat/add-ntp-role

4. Open a Pull Request in the Gitea UI

5. Review the diff, approve, merge

6. Delete the feature branch after merge

7. Return to main locally

1
2

git checkout main
git pull origin main

• Created a new branch and switched to it.
• Pushed the feature branch to Gitea (the PR workflow handles the merge).
• After the PR is merged, I switch back to main locally and pull the latest changes.

09 Verification

I ran through a final checklist to confirm everything is working.

Gitea containers running:

1

docker compose -f /opt/gitea/docker-compose.yml ps

Both gitea and gitea-db should show status of Up.

SSH connectivity from ansible-ctrl:

1

ssh -T git@gitea

I verified branch protection is active by attempting a direct push to main:

1
2
3
4

echo "test" >> README.md
git add README.md
git commit -m "test: verify branch protection"
git push origin main

Now I have a self-hosted Gitea instance running on a dedicated VM with PostgresSQL backend, SSH key authentication configured between ansible-ctrl and Gitea.