# Common Gitea Transfer Failure Modes

## Dot Paths 403 In Gitea UI

Cause: reverse proxy blocks dot directories.

Fix: adjust the proxy rule for Gitea. Do not rename workflow directories.

## Postgres Connection Refused

Cause: CI app connects to `127.0.0.1` while Postgres runs as a service container.

Fix: use service hostname such as `postgres` and add readiness checks.

## Runner Job Never Starts

Cause: workflow `runs-on` label does not match registered runner labels.

Fix: use generic labels and verify with `tea api admin/actions/runners`.

## Image Pull Fails

Cause: wrong registry hostname, missing Docker daemon trust, or private package auth issue.

Fix: verify image reference by pulling on the runner host, then use the same host/port in the workflow.

## Deploy Fails For Missing Secrets

Cause: Gitea Actions secrets are not configured yet.

Fix: add a preflight skip or configure secrets. File follow-up work instead of leaving the default branch red.

## OpenCode Review Has No Context

Cause: workflow passed only a diff and did not checkout the PR head tree.

Fix: fetch the PR diff through the Gitea API, then shallow-checkout the PR head SHA with `fetch-depth: 1` and `persist-credentials: false`.

## Branch Tracks Old GitHub Remote

Cause: local branch upstream still points to `github/{branch}` after remote cutover.

Fix only if requested or useful:

```bash
git branch --set-upstream-to=origin/{branch} {branch}
```