Hands-on Lab

How to upgrade Gitea 1.27 to 28 with Docker without losing webhooks

October 21, 2026 4 min

0 / 8

Cheat sheet

Found it useful? Don't miss the next lab

The video has captions and a transcript. Everything it shows is written out, step by step, below. Cheat sheet with every command

0:00 / 0:00

We pin GITEA_TAG=1.27.3 in .env and the official docker.gitea.com/gitea image reads it through ${GITEA_TAG}. INSTALL_LOCK=true skips the web install wizard and DB_TYPE=sqlite3 keeps the database inside the gitea_data volume. The two ALLOWED_HOST_LIST=private keys reproduce a typical 1.27 setup: the [security] one and the legacy [webhook] one. The hook service is an nginx that receives webhooks inside the Compose network.

mkdir -p /root/gitea && cd /root/gitea && echo 'GITEA_TAG=1.27.3' > .env && cat > docker-compose.yml <<'EOF'
services:
  gitea:
    image: docker.gitea.com/gitea:${GITEA_TAG}
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      GITEA__database__DB_TYPE: sqlite3
      GITEA__security__INSTALL_LOCK: "true"
      GITEA__security__ALLOWED_HOST_LIST: private
      GITEA__webhook__ALLOWED_HOST_LIST: private
    ports:
      - "3000:3000"
    volumes:
      - gitea_data:/data
  hook:
    image: nginx:1.29-alpine
volumes:
  gitea_data:
EOF
docker compose up -d --quiet-pull

I did it

We wait in a loop of up to 120 s for /api/healthz to answer, the real signal that Gitea is serving requests, and ask the API for the version. The startup log shows a deprecation warning: the [webhook] ALLOWED_HOST_LIST key stops being read in v28.0.0.

cd /root/gitea && for i in $(seq 1 60); do curl -sf http://localhost:3000/api/healthz >/dev/null && break; sleep 2; done; curl -s http://localhost:3000/api/healthz | jq -r '"healthz: " + .status'; curl -s http://localhost:3000/api/v1/version; echo; docker compose logs gitea | grep -m1 -o 'Deprecation: config option .\[webhook\].ALLOWED_HOST_LIST. present'; docker compose logs gitea | grep -m1 -o 'removed in v28.0.0'

What this proves

healthz: pass the Gitea health endpoint answers pass Goal · you know the instance is ready before you create anything
{"version":"1.27.3"} the API reports version 1.27.3, the one in .env Goal · you have the starting point of the upgrade confirmed
removed in v28.0.0 1.27.3 warns that the [webhook] key is removed in 28 Goal · you know which app.ini line to clean before upgrading

gitea admin user create makes the account without going through the web UI. We run it with -u git because Gitea runs as that user inside the image, so whatever the CLI touches stays owned by it. The changeme password is a throwaway value and --must-change-password=false lets us use it on the API without changing it.

cd /root/gitea && docker compose exec -u git gitea gitea admin user create --admin --username labadmin --password changeme --email labadmin@lab.local --must-change-password=false

I did it

We list only the administrator accounts. labadmin shows up with its email and IsActive set to true, so we can now authenticate against the API with it.

cd /root/gitea && docker compose exec -u git gitea gitea admin user list --admin

What this proves

labadmin@lab.local the labadmin account exists with its email Goal · you have a user to create the repository and the webhook with

POST /user/repos creates demo with a first commit (auto_init). POST /repos/labadmin/demo/hooks registers a gitea-type webhook that fires on every push to http://hook/ci, the nginx on the Compose network, a private IP that ALLOWED_HOST_LIST=private allows. POST /hooks/1/tests asks Gitea for a test delivery and answers 204.

cd /root/gitea && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/user/repos -d '{"name":"demo","auto_init":true}' | jq -c '{full_name,default_branch}' && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks -d '{"type":"gitea","config":{"url":"http://hook/ci","content_type":"json"},"events":["push"],"active":true}' | jq -c '{id,active,url:.config.url}' && curl -s -o /dev/null -w 'test delivery: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/1/tests

I did it

Delivery is asynchronous, so we wait up to 30 s for it to show up in the nginx access log. The 404 comes from nginx, which has no page at /ci: what matters is that Gitea's request reached its target on the internal network.

cd /root/gitea && for i in $(seq 1 30); do docker compose logs hook | grep -q 'POST /ci' && break; sleep 1; done; echo "deliveries: $(docker compose logs hook | grep -c 'POST /ci.*Go-http-client')"; docker compose logs hook | grep -m1 -o '"POST /ci HTTP/1.1" 404 .*Go-http-client/1.1'

What this proves

deliveries: 1 nginx logs 1 POST request to /ci Goal · you have a webhook delivering on 1.27.3, the baseline to compare against after the upgrade
Go-http-client/1.1 the request comes from Gitea's HTTP client Goal · you rule out that the log line came from anywhere else

The Gitea documentation asks you to stop the instance before copying, because the database and the repositories change together. With SQLite the database lives inside /data, so the volume tar keeps repositories, app.ini and database in a single file. The volume is called gitea_gitea_data: the Compose project name plus the volume name.

cd /root/gitea && docker compose stop gitea && mkdir -p backup && docker run --rm -q -v gitea_gitea_data:/data:ro -v "$PWD/backup":/backup alpine:3.22 tar czf /backup/gitea-data-1.27.3.tar.gz -C /data .

I did it

We confirm the container is in the exited state, so nothing was writing while we copied, and list the archive contents: the configuration, the SQLite database and the demo repository. With that backup, going back to 1.27.3 means restoring the volume and the tag.

cd /root/gitea && docker compose ps -a gitea --format '{{.Service}} {{.State}}' && ls -lh backup && tar tzf backup/gitea-data-1.27.3.tar.gz | grep -E 'app.ini|gitea.db|demo.git/HEAD'

What this proves

gitea exited the gitea service is stopped Goal · you know the backup is consistent, with no half-written changes
./gitea/gitea.db the SQLite database is inside the archive Goal · you have everything needed to go back if 28 fails

The sed deletes the egress keys that 28 treats as obsolete, and the [webhook] one only inside its section, so the [security] one is left alone. In Compose we drop the [webhook] variable, because environment-to-ini would write it back. In its place we set EGRESS_MODE=strict, which in 28 lets webhooks go out only to hosts on the list.

cd /root/gitea && docker run --rm -q -v gitea_gitea_data:/data alpine:3.22 sed -i -e '/^ALLOW_LOCALNETWORKS/d' -e '/^ALLOWED_DOMAINS/d' -e '/^BLOCKED_DOMAINS/d' -e '/^\[webhook\]/,/^\[/{/^ALLOWED_HOST_LIST/d}' /data/gitea/conf/app.ini && sed -i 's/GITEA__webhook__ALLOWED_HOST_LIST: private/GITEA__security__EGRESS_MODE: strict/' docker-compose.yml

I did it

We count the ALLOWED_HOST_LIST lines left in app.ini and how many sit inside [webhook], and review the [security] variables in Compose. That way 28 starts without the key it no longer reads.

cd /root/gitea && docker run --rm -q -v gitea_gitea_data:/data:ro alpine:3.22 sh -c 'grep -n "^ALLOWED_HOST_LIST" /data/gitea/conf/app.ini; echo "[webhook] ALLOWED_HOST_LIST: $(sed -n "/^\[webhook\]/,/^\[/p" /data/gitea/conf/app.ini | grep -c ALLOWED_HOST_LIST)"'; grep -n 'GITEA__security' docker-compose.yml

What this proves

[webhook] ALLOWED_HOST_LIST: 0 the [webhook] section no longer has ALLOWED_HOST_LIST Goal · 28 will not find the obsolete key at startup
GITEA__security__EGRESS_MODE: strict Compose sets EGRESS_MODE strict in [security] Goal · you set up 28 to deliver only to hosts on the list

The upgrade is one line of .env. docker compose pull downloads docker.gitea.com/gitea:28.0.0 and up -d recreates only the gitea service with the new image and the same volume.

cd /root/gitea && sed -i 's/^GITEA_TAG=.*/GITEA_TAG=28.0.0/' .env && cat .env && docker compose pull -q gitea && docker compose up -d gitea

I did it

Gitea applies the database migrations at startup, before serving HTTP, so we wait on /api/healthz again. We count the migrations in the log, from 343 to 355, and the [E] or [F] lines: with app.ini clean neither the deprecation warning nor any error shows up.

cd /root/gitea && for i in $(seq 1 60); do curl -sf http://localhost:3000/api/healthz >/dev/null && break; sleep 2; done; curl -s http://localhost:3000/api/v1/version; echo; echo "migrations: $(docker compose logs gitea | grep -c 'Migration\[')"; docker compose logs gitea | grep -m1 -o 'Migration\[343\].*'; docker compose logs gitea | grep -m1 -o 'Migration\[355\].*'; echo "errors: $(docker compose logs gitea | grep -cE '\[(E|F)\]')"

What this proves

{"version":"28.0.0"} the API reports version 28.0.0 Goal · you confirm the upgrade has been applied
migrations: 13 Gitea applied 13 schema migrations Goal · you know the database no longer works for 1.27.3 without the backup
errors: 0 the 28 log has no [E] or [F] lines Goal · you check that cleaning app.ini avoided warnings and startup failures

We fire another test delivery of webhook 1, the one we created on 1.27.3. Then we register webhook 2 pointing at https://example.com/ci to see what EGRESS_MODE=strict does with a public host outside ALLOWED_HOST_LIST. Both test requests answer 204: Gitea queues the delivery and attempts it afterwards.

cd /root/gitea && curl -s -o /dev/null -w 'LAN hook test: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/1/tests && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks -d '{"type":"gitea","config":{"url":"https://example.com/ci","content_type":"json"},"events":["push"],"active":true}' | jq -c '{id,url:.config.url}' && curl -s -o /dev/null -w 'public hook test: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/2/tests

I did it

The 28.0.0 API returns the labadmin/demo repository and both webhooks. The nginx log now adds up to 2 deliveries, the 1.27.3 one and the 28 one, so the webhook survived the upgrade and still reaches the internal network. The example.com delivery fails with denied by egress policy, because in strict mode a public host outside the list gets nothing.

cd /root/gitea && curl -s http://localhost:3000/api/v1/version; echo; curl -s -u labadmin:changeme http://localhost:3000/api/v1/repos/labadmin/demo | jq -r '"repo: " + .full_name'; curl -s -u labadmin:changeme http://localhost:3000/api/v1/repos/labadmin/demo/hooks | jq -r '.[] | "hook \(.id): \(.config.url)"'; for i in $(seq 1 30); do [ "$(docker compose logs hook | grep -c 'POST /ci.*Go-http-client')" -ge 2 ] && docker compose logs gitea | grep -q 'denied by egress policy' && break; sleep 1; done; echo "LAN deliveries: $(docker compose logs hook | grep -c 'POST /ci.*Go-http-client')"; docker compose logs gitea | grep -m1 -o 'https://example.com/ci": dial tcp .*denied by egress policy'

What this proves

repo: labadmin/demo the repository created on 1.27.3 is still there on 28 Goal · you check the upgrade lost no data
LAN deliveries: 2 nginx received a second delivery, now from 28 Goal · you know the internal-network webhook still works after the upgrade
denied by egress policy 28 blocks the example.com delivery with EGRESS_MODE strict Goal · you confirm the host list is still exclusive on 28

docker compose down stops and removes the gitea and hook containers and the project network, and -v also deletes the gitea_gitea_data volume. The backup in backup/ stays on disk, outside Docker.

cd /root/gitea && docker compose down -v

I did it

We count the remaining containers and Gitea volumes: 0 in both cases. The gitea-data-1.27.3.tar.gz archive is still in backup/, which is what you would keep on a real server.

cd /root/gitea && echo "containers: $(docker ps -aq | wc -l)"; echo "gitea volumes: $(docker volume ls -q | grep -c gitea_data)"; ls backup

What this proves

containers: 0 no container is left Goal · you leave the machine as it was before the lab
gitea volumes: 0 the Gitea volume has been deleted Goal · you know down -v also removed the persistent data

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Video transcript

0:00 Gitea 28 on Docker, with the repository and webhook from 1.27 intact.
0:07 We write the Compose file for Gitea 1.27.3, with the version in .env,
0:13 SQLite and an nginx that will receive the webhooks.
0:16 The version lives on a single line of the .env file, and Compose reads it at
0:21 startup.
0:22 We take Gitea from 1.27.3 to 28.0.0
0:28 without losing the repository or the webhook.
0:31 28 changes webhook egress, the app.ini keys and the schema.
0:36 With healthz at pass, the API reports 1.27.3, and the log warns
0:42 that the [webhook] key goes away in 28.
0:46 We create the labadmin administrator with the Gitea CLI, as the git user inside the
0:51 container.
0:52 We check it:
0:53 the administrator list includes labadmin, active.
1:01 Through the API we create the demo repository, add a webhook pointing at the
1:06 nginx and fire a test delivery.
1:09 nginx logs 1 delivery to /ci from Gitea's HTTP client.
1:17 The order matters:
1:19 stop, back up, clean app.ini and only then change the tag.
1:23 We stop Gitea and archive the volume with tar from a read-only alpine container.
1:29 Gitea is stopped and the backup holds app.ini, the database and the demo
1:34 repository.
1:39 The image's startup script writes every GITEA variable into app.ini and never
1:44 deletes any.
1:45 We delete the legacy keys from app.ini with the article's sed, and set
1:49 EGRESS_MODE strict in Compose.
1:52 app.ini keeps a single ALLOWED_HOST_LIST, the [security] one, and none in [webhook].
2:02 We change GITEA_TAG to 28.0.0 in .env, pull the new image
2:08 and recreate the container.
2:10 The API now reports 28.0.0, with 13 schema migrations
2:16 and 0 errors in the log.
2:20 In 28, EGRESS_MODE decides whether the host list is exclusive or only guards the
2:26 internal network.
2:27 We test the internal webhook and create another one to example.com, a public host
2:33 outside the list.
2:34 On 28 the repository and the webhook are still there, now at 2 deliveries.
2:40 The example.com one is denied by the egress policy.
2:45 We bring the project down and delete its volume with docker compose down -v.
2:52 No containers or volume are left, and the backup is still on disk.

This lab reproduces in the terminal the guide to upgrade Gitea 28 with Docker: we start from Gitea 1.27.3 on Docker Compose, with the version pinned in GITEA_TAG inside .env, and take it to 28.0.0 without losing the repository or the webhook. If you do not run Gitea yet, start with how to install Gitea with Docker.

What changes when you go from Gitea 1.27 to 28

Gitea 28.0.0 is the release that follows 1.27.3: the official Gitea 28.0.0 announcement explains that the project dropped the 1. prefix from its version numbers. On Docker one line of .env changes, but 28 applies 13 schema migrations and changes how webhooks leave Gitea: they go through an egress policy, EGRESS_MODE, which in strict mode only delivers to hosts on ALLOWED_HOST_LIST. The change landed with Gitea PR 39426.

What the capture proves

Every step in the video really ran. The capture leaves four pieces of evidence:

the API goes from {"version":"1.27.3"} to {"version":"28.0.0"}
28 logs 13 migrations, from 343 to 355, and 0 error lines
the labadmin/demo repository and the webhook to the nginx on the internal network are still there, and nginx counts 2 deliveries, one per version
with EGRESS_MODE=strict, a webhook to example.com is rejected with denied by egress policy

The backup, with Gitea stopped

The Gitea backup documentation asks you to stop the instance before copying. The lab uses SQLite, so the database lives in the /data volume and a single tar keeps repositories, app.ini and database. The original article uses PostgreSQL and adds a pg_dump; if you want to practise the backup and restore pattern, it is in the Docker volume backup and restore lab.

Why the sed on app.ini

The image’s startup script writes every GITEA__ variable into app.ini and never deletes anything. That is why the legacy [webhook] ALLOWED_HOST_LIST key stays in the file even if you drop it from Compose, and 1.27.3 already warns at startup that it is removed in v28.0.0. The lab deletes it with the same sed as the article, with Gitea stopped. The ${GITEA_TAG} substitution is Docker Compose variable interpolation; if Compose is new to you, go through the lab on multi-container apps with Docker Compose.

What this lab does not cover

The article also tests mirrors, the 400-day Actions retention with RUN_RETENTION_DAYS, the restart loop caused by a wildcard in BLOCKED_DOMAINS and the rollback with pg_restore. We do not repeat them here: read those sections of the guide before upgrading an instance that uses them, along with the official Gitea upgrade guide.

FAQ

Why does Gitea go from 1.27 to 28 and not 1.28?

The project dropped the historical 1. prefix from its version numbers, so the release after 1.27.3 is 28.0.0. On Docker only the image tag changes: docker.gitea.com/gitea:28.0.0.

Do I need to stop Gitea to take the backup?

Yes. The Gitea documentation asks you to stop the instance before copying, because the database and the repositories change together. In this lab we stop the service with docker compose stop gitea and archive the volume with tar from an alpine container mounted read-only.

Why clean app.ini if I already changed docker-compose.yml?

Because the image's startup script writes every GITEA__ variable into app.ini and never deletes any. The [webhook] ALLOWED_HOST_LIST key stays in the file even if you drop it from Compose, and 1.27.3 already warns that 28 stops reading it.

Can I go back to Gitea 1.27 after upgrading?

Only by restoring the backup. 28.0.0 applies 13 schema migrations at startup and, as the original guide shows, 1.27.3 refuses to start on a migrated database. Restore the volume from the tar, set GITEA_TAG back to 1.27.3 and start again.

Cheat sheet

mkdir -p /root/gitea && cd /root/gitea && echo 'GITEA_TAG=1.27.3' > .env && cat > docker-compose.yml <<'EOF'
services:
  gitea:
    image: docker.gitea.com/gitea:${GITEA_TAG}
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      GITEA__database__DB_TYPE: sqlite3
      GITEA__security__INSTALL_LOCK: "true"
      GITEA__security__ALLOWED_HOST_LIST: private
      GITEA__webhook__ALLOWED_HOST_LIST: private
    ports:
      - "3000:3000"
    volumes:
      - gitea_data:/data
  hook:
    image: nginx:1.29-alpine
volumes:
  gitea_data:
EOF
docker compose up -d --quiet-pull

cd /root/gitea && docker compose exec -u git gitea gitea admin user create --admin --username labadmin --password changeme --email labadmin@lab.local --must-change-password=false

cd /root/gitea && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/user/repos -d '{"name":"demo","auto_init":true}' | jq -c '{full_name,default_branch}' && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks -d '{"type":"gitea","config":{"url":"http://hook/ci","content_type":"json"},"events":["push"],"active":true}' | jq -c '{id,active,url:.config.url}' && curl -s -o /dev/null -w 'test delivery: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/1/tests

cd /root/gitea && docker compose stop gitea && mkdir -p backup && docker run --rm -q -v gitea_gitea_data:/data:ro -v "$PWD/backup":/backup alpine:3.22 tar czf /backup/gitea-data-1.27.3.tar.gz -C /data .

cd /root/gitea && docker run --rm -q -v gitea_gitea_data:/data alpine:3.22 sed -i -e '/^ALLOW_LOCALNETWORKS/d' -e '/^ALLOWED_DOMAINS/d' -e '/^BLOCKED_DOMAINS/d' -e '/^\[webhook\]/,/^\[/{/^ALLOWED_HOST_LIST/d}' /data/gitea/conf/app.ini && sed -i 's/GITEA__webhook__ALLOWED_HOST_LIST: private/GITEA__security__EGRESS_MODE: strict/' docker-compose.yml

cd /root/gitea && sed -i 's/^GITEA_TAG=.*/GITEA_TAG=28.0.0/' .env && cat .env && docker compose pull -q gitea && docker compose up -d gitea

cd /root/gitea && curl -s -o /dev/null -w 'LAN hook test: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/1/tests && curl -s -u labadmin:changeme -H 'Content-Type: application/json' -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks -d '{"type":"gitea","config":{"url":"https://example.com/ci","content_type":"json"},"events":["push"],"active":true}' | jq -c '{id,url:.config.url}' && curl -s -o /dev/null -w 'public hook test: %{http_code}\n' -u labadmin:changeme -X POST http://localhost:3000/api/v1/repos/labadmin/demo/hooks/2/tests

cd /root/gitea && docker compose down -v

Found it useful? Don't miss the next lab

Subscribe to the newsletter

What changes when you go from Gitea 1.27 to 28

What the capture proves

The backup, with Gitea stopped

Why the sed on app.ini

What this lab does not cover

FAQ

Why does Gitea go from 1.27 to 28 and not 1.28?

Do I need to stop Gitea to take the backup?

Why clean app.ini if I already changed docker-compose.yml?

Can I go back to Gitea 1.27 after upgrading?

Cheat sheet