skills/gitea-transfer/SKILL.md

---
name: gitea-transfer
description: Guide for transferring repositories from GitHub to self-hosted Gitea, including remotes, branches, PR migration, Gitea Actions porting, runner images, and cutover verification.
---

# Gitea Transfer

## When To Use

Use this skill when moving a repository from GitHub to self-hosted Gitea, converting a Gitea mirror into the canonical source repo, migrating active branches and pull requests, porting GitHub Actions to Gitea Actions, or designing runner job images for CI.

## Operating Principles

- Treat Gitea as canonical only after confirming the repo is no longer a mirror and the default branch is pushed.
- Keep the GitHub remote as a recovery/reference remote unless the user explicitly asks to remove it.
- Prefer `tea` or the Gitea API for Gitea repository, pull request, Actions, and runner operations.
- Do not use `gh` for Gitea work.
- Do not paste, log, commit, or store registration tokens, API tokens, deploy keys, or package credentials.
- Avoid Gitea Actions secret names beginning with `GITEA_` or `GITHUB_`; those prefixes are reserved or confusing in Gitea/GitHub-compatible runners.
- Do not modify ignored local config files such as `bunfig.toml` unless the user explicitly requests it.
- Do not merge pull requests unless the user explicitly approves the merge.
- Do not force-push or rewrite shared branches unless the user explicitly approves it.
- Verify every cutover step with API or git status output before moving on.

## Preflight Checks

Confirm local state and remotes:

```bash
git status --short --branch
git remote -v
git branch --show-current
```

Confirm the Gitea CLI is authenticated and targeting the expected instance:

```bash
tea login list
tea repo ls
```

Confirm the Gitea repository exists and inspect settings:

```bash
tea api repos/{owner}/{repo}
```

If Gitea is behind Nginx or another reverse proxy, verify dot directories are reachable. A common Forge/Nginx rule blocks paths such as `.github`, `.gitea`, `.codex`, and `.well-known`:

```nginx
location ~ /\.(?!well-known).* {
    deny all;
}
```

For Gitea, that rule can break UI/API access to workflow files and agent config paths. Update the reverse proxy deliberately rather than working around it in git.

## Convert Mirror To Source

If the Gitea repository was imported as a mirror, convert it to a normal source repository before cutover. Use the Gitea UI or API, then verify:

```bash
tea api repos/{owner}/{repo}
```

Check that `mirror` is `false` and the expected default branch is set.

Enable repository features as needed:

```bash
tea api --method PATCH repos/{owner}/{repo} \
  --field has_pull_requests=true \
  --field has_actions=true
```

Use the actual supported fields for the installed Gitea version. Re-read the repository after patching.

## Remote Cutover

Keep GitHub as a named fallback remote and make Gitea `origin`:

```bash
git remote rename origin github
git remote add origin ssh://git@git.example.com:30009/{owner}/{repo}.git
git remote -v
```

If `origin` already points elsewhere, adjust non-destructively:

```bash
git remote set-url origin ssh://git@git.example.com:30009/{owner}/{repo}.git
git remote add github git@github.com:{owner-or-org}/{repo}.git
```

Push the default branch first:

```bash
git fetch github --prune
git push origin {default-branch}:{default-branch}
```

Verify Gitea sees the branch:

```bash
tea api repos/{owner}/{repo}/branches/{default-branch}
```

## Branch Migration

List active GitHub branches that need to move:

```bash
git branch -r
```

Push only active work branches, not every stale remote branch by default:

```bash
git push origin github/{branch-name}:refs/heads/{branch-name}
```

For multiple open PR heads, script carefully from reviewed data. Avoid pushing deleted/stale branches blindly.

Verify pushed branches:

```bash
tea api repos/{owner}/{repo}/branches
```

## Pull Request Migration

Gitea does not automatically migrate all GitHub PR review history during a basic repo transfer. Recreate open PRs with enough context to continue work:

- title
- body
- base branch
- head branch
- draft/WIP state in title or body if Gitea draft support is not available
- link back to the original GitHub PR

Use the Gitea API or `tea`:

```bash
tea pr create \
  --repo {owner}/{repo} \
  --base {base-branch} \
  --head {head-branch} \
  --title "{title}" \
  --description "{body}"
```

After creating each PR, verify it is open, conflict status is correct, and the branch is correct:

```bash
tea pr {index} --repo {owner}/{repo}
```

If comments/reviews matter, add a short migration note to the PR body linking to the original GitHub PR rather than attempting to recreate every review event.

## CI Workflow Porting

Gitea Actions workflows live in `.gitea/workflows/`. GitHub workflows can remain temporarily in `.github/workflows/` during transition, but do not assume they run on Gitea.

Port workflows incrementally:

- Start with tests.
- Then add build/deploy workflows.
- Keep workflow syntax close to GitHub Actions where Gitea supports it.
- Validate YAML before pushing.
- Prefer small commits so each Actions failure identifies one change.

Example validation:

```bash
ruby -e "require 'yaml'; YAML.load_file('.gitea/workflows/tests.yml'); puts 'ok'"
git diff --check
```

Common changes when porting:

- Replace GitHub-only secrets with Gitea Actions secrets.
- Use neutral secret names such as `REGISTRY_USERNAME`, `REGISTRY_TOKEN`, `REVIEW_BOT_TOKEN`, and `OPENCODE_GO_TOKEN`.
- Remove GitHub Packages auth if the private package dependency is removed or mirrored elsewhere.
- Replace GitHub-hosted assumptions with Gitea runner/job container assumptions.
- Ensure `actions/checkout` version works with the installed Gitea Actions runner.
- Use service hostnames for service containers instead of `127.0.0.1`.
- Add explicit service readiness checks for databases.
- Do not rely on `permissions:` for security-sensitive sandboxing in Gitea Actions; some Gitea versions ignore it.

For Postgres services, use the service name as the host:

```yaml
services:
  postgres:
    image: postgres:16
    env:
      POSTGRES_DB: app_test
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password

env:
  DB_HOST: postgres
```

Add a readiness loop before running tests:

```bash
until PGPASSWORD=password pg_isready -h postgres -U postgres; do
  sleep 1
done
```

## Package Registry Cutover

Identify GitHub-specific package auth before enabling Gitea CI:

- npm/Bun scopes using `npm.pkg.github.com`
- Composer auth for GitHub-hosted private packages
- workflow steps writing `.npmrc` or package auth
- lockfiles referencing private GitHub package tarballs

Options:

- Remove the dependency if it can be replaced locally.
- Mirror the package to Gitea Packages.
- Keep GitHub Packages temporarily and configure Gitea secrets deliberately.

Do not leave workflows requiring secrets that no longer exist. If deploy secrets are absent during cutover, prefer a clear skip for deploy-only workflows so the default branch is not red while secrets are being configured.

## Runner Image Strategy

Prefer job containers over custom runner labels for language/runtime selection.

Use shared CI job images when several repositories need the same runtime stack. The current shared image family is:

- `git.bayliss.cloud/harry/gitea-ci-runner:php8.2`
- `git.bayliss.cloud/harry/gitea-ci-runner:php8.3`
- `git.bayliss.cloud/harry/gitea-ci-runner:php8.4`
- `git.bayliss.cloud/harry/gitea-ci-runner:php8.5`
- `git.bayliss.cloud/harry/gitea-ci-runner:latest`

`latest` points to PHP `8.5`. Repositories should usually hardcode the PHP tag they require instead of using `latest`, so runtime upgrades are explicit per repository.

Good pattern:

```yaml
jobs:
  tests:
    runs-on: ubuntu-latest
    container:
      image: git.bayliss.cloud/harry/gitea-ci-runner:php8.2
```

Avoid creating labels such as `stratbase-php82` just to pick an image. Labels select eligible runners; job containers select the runtime image. This keeps the runner reusable across repositories.

Use an instance-level or organization-level runner with generic labels such as:

- `ubuntu-latest`
- `ubuntu-24.04`
- `ubuntu-22.04`

If runner labels change, the runner usually needs re-registration because `.runner` pins registration details. App UI fields called "Labels Configuration" may refer to Docker metadata, not Gitea runner labels. Verify actual labels through the API:

```bash
tea api admin/actions/runners
```

## Building A CI Job Image

Create or update a shared image when workflows need system dependencies that are expensive or brittle to install per run. Prefer a central image repository over per-application image repositories unless the runtime is truly application-specific.

Current shared image repository:

```text
ssh://git@git.bayliss.cloud:30009/harry/gitea-ci-runner.git
https://git.bayliss.cloud/harry/gitea-ci-runner
```

Current shared PHP/Laravel CI image contents:

- base Gitea runner job image
- PHP CLI for `8.2`, `8.3`, `8.4`, and `8.5`, selected with `ARG PHP_VERSION`
- Composer 2
- Bun
- Node.js, `npm`, and `npx`
- Go
- Python 3, `pip`, and `venv`
- `jq`
- database and cache client tools such as `postgresql-client` and `redis-tools`
- common PHP extensions including `rdkafka`, `redis`, `pcov`, `xdebug`, `imagick`, `imap`, `pgsql`, `mysql`, `sqlite3`, `gmp`, and `gd`

Do not add MongoDB to the shared image unless a repository has a real runtime or CI need for it.

Shared Dockerfile pattern:

```dockerfile
FROM docker.gitea.com/runner-images:ubuntu-latest

ARG PHP_VERSION=8.5

ENV DEBIAN_FRONTEND=noninteractive
ENV BUN_INSTALL=/root/.bun
ENV PATH="/root/.bun/bin:${PATH}"

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        git \
        golang-go \
        gnupg \
        jq \
        lsb-release \
        postgresql-client \
        python3 \
        python3-pip \
        python3-venv \
        redis-tools \
        software-properties-common \
        unzip \
    && install -d -m 0755 /etc/apt/keyrings \
    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
    && add-apt-repository ppa:ondrej/php -y \
    && apt-get update \
    && apt-get install -y --no-install-recommends \
        nodejs \
        php${PHP_VERSION} \
        php${PHP_VERSION}-bcmath \
        php${PHP_VERSION}-curl \
        php${PHP_VERSION}-gd \
        php${PHP_VERSION}-imagick \
        php${PHP_VERSION}-imap \
        php${PHP_VERSION}-intl \
        php${PHP_VERSION}-mbstring \
        php${PHP_VERSION}-mysql \
        php${PHP_VERSION}-pcov \
        php${PHP_VERSION}-pgsql \
        php${PHP_VERSION}-redis \
        php${PHP_VERSION}-rdkafka \
        php${PHP_VERSION}-sqlite3 \
        php${PHP_VERSION}-xdebug \
        php${PHP_VERSION}-xml \
        php${PHP_VERSION}-zip \
    && update-alternatives --set php /usr/bin/php${PHP_VERSION} \
    && curl -fsSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
    && curl -fsSL https://bun.sh/install | bash \
    && ln -sf /root/.bun/bin/bun /usr/local/bin/bun \
    && ln -sf /root/.bun/bin/bunx /usr/local/bin/bunx \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN php -v \
    && php -m \
    && composer --version \
    && go version \
    && bun --version \
    && node --version \
    && python3 --version \
    && pg_isready --version
```

Build and push manually only when necessary:

```bash
docker build --build-arg PHP_VERSION=8.2 -t git.bayliss.cloud/harry/gitea-ci-runner:php8.2 -f docker/Dockerfile .
docker push git.bayliss.cloud/harry/gitea-ci-runner:php8.2
```

Prefer the image repository workflow for normal updates. Use a matrix over the supported PHP versions and push `latest` only from PHP `8.5`:

```yaml
env:
  REGISTRY: git.bayliss.cloud
  IMAGE_NAME: harry/gitea-ci-runner

jobs:
  build:
    strategy:
      matrix:
        php-version:
          - '8.2'
          - '8.3'
          - '8.4'
          - '8.5'

    steps:
      - uses: actions/checkout@v4

      - name: Check registry credentials
        env:
          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: |
          if [ -z "$REGISTRY_USERNAME" ] || [ -z "$REGISTRY_TOKEN" ]; then
            echo "Skipping image publish because REGISTRY_USERNAME or REGISTRY_TOKEN is missing."
            echo "SKIP_IMAGE_PUBLISH=true" >> "$GITHUB_ENV"
          fi

      - name: Login to Gitea registry
        if: env.SKIP_IMAGE_PUBLISH != 'true'
        env:
          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: echo "$REGISTRY_TOKEN" | docker login "$REGISTRY" --username "$REGISTRY_USERNAME" --password-stdin

      - name: Build and push version tag
        if: env.SKIP_IMAGE_PUBLISH != 'true'
        run: |
          docker build \
            --build-arg PHP_VERSION="${{ matrix.php-version }}" \
            --tag "$REGISTRY/$IMAGE_NAME:php${{ matrix.php-version }}" \
            --file docker/Dockerfile \
            .
          docker push "$REGISTRY/$IMAGE_NAME:php${{ matrix.php-version }}"

      - name: Push latest tag
        if: env.SKIP_IMAGE_PUBLISH != 'true' && matrix.php-version == '8.5'
        run: |
          docker tag "$REGISTRY/$IMAGE_NAME:php${{ matrix.php-version }}" "$REGISTRY/$IMAGE_NAME:latest"
          docker push "$REGISTRY/$IMAGE_NAME:latest"
```

If the runner host exposes the Gitea registry locally, prefer the runner-local endpoint in workflow job containers for faster pulls:

```yaml
container:
  image: localhost:30008/harry/gitea-ci-runner:php8.2
```

Do not include `http://` in Docker image references. Configure insecure/local registry trust at the Docker daemon level if needed.

## OpenCode PR Review Workflow

Use this pattern when adding a repo-scoped OpenCode reviewer to Gitea Actions.

Core behavior:

- Trigger only from PR comments containing `/review`.
- Do not auto-review on PR open or synchronize events for the first version.
- Run OpenCode read-only.
- Post or update one aggregate PR comment instead of line comments.
- Use the PR head checkout for repository context, but keep checkout shallow.
- Do not expose Gitea API tokens to OpenCode.

Required secrets:

- `REVIEW_BOT_TOKEN`: Gitea token for reading the repository/PR and writing issue comments.
- `OPENCODE_GO_TOKEN`: OpenCode Go API token.

Recommended token permissions for `REVIEW_BOT_TOKEN`:

- `read:repository`
- `read:issue`
- `write:issue`

Recommended workflow shape:

```yaml
on:
  issue_comment:
    types:
      - created
  workflow_dispatch:

jobs:
  review:
    runs-on: ubuntu-latest
    container:
      image: git.bayliss.cloud/harry/gitea-ci-runner:php8.2
```

In a preparation step:

- Read `$GITHUB_EVENT_PATH` with `jq`.
- Skip unless the event action is `created`.
- Skip unless the issue is a pull request.
- Skip unless the comment contains `/review`.
- Fetch pull request metadata from `GET /repos/{owner}/{repo}/pulls/{number}`.
- Fetch the diff from `GET /repos/{owner}/{repo}/pulls/{number}.diff`.
- Export `PR_NUMBER`, `REPO`, `BASE_BRANCH`, `HEAD_BRANCH`, and `HEAD_SHA` to `$GITHUB_ENV`.

Checkout the PR head after preparation:

```yaml
- name: Checkout PR head
  if: env.SKIP_OPENCODE_REVIEW != 'true'
  uses: actions/checkout@v4
  with:
    ref: ${{ env.HEAD_SHA }}
    fetch-depth: 1
    persist-credentials: false
```

Avoid `fetch-depth: 0` unless full history is required; full-history checkout can make review runs slow on Gitea runners.

Generate OpenCode auth at runtime from `OPENCODE_GO_TOKEN`:

```bash
mkdir -p "$HOME/.local/share/opencode"
jq -n --arg token "$OPENCODE_GO_TOKEN" '{"opencode-go": {"type": "api", "key": $token}}' > "$HOME/.local/share/opencode/auth.json"
```

Disable mutation tools and unset repository tokens before invoking OpenCode:

```bash
export OPENCODE_CONFIG_CONTENT='{"tools":{"write":false,"edit":false,"bash":false},"permission":{"edit":"deny","bash":"deny"},"share":"disabled","autoupdate":false}'
unset OPENCODE_GO_TOKEN REVIEW_BOT_TOKEN GITEA_TOKEN GITHUB_TOKEN

opencode run \
  --model "${REVIEW_MODEL:-opencode-go/glm-5.1}" \
  --file /tmp/opencode-pr.diff \
  --title "PR #$PR_NUMBER review" \
  "Review this pull request diff for bugs, security issues, behavior regressions, and missing tests. Use the checked-out PR head tree for repository context. Focus on actionable findings. If there are no findings, say so clearly. Do not suggest style-only changes. Output Markdown with concise sections." \
  > /tmp/opencode-review.md
```

Use a stable marker in the review comment body so later `/review` runs update the same comment:

```text
<!-- opencode-review -->
```

Gitea Actions logs can be awkward to fetch on versions before `1.26`; if `tea actions runs logs` is unavailable or incomplete, inspect run/task state through the Gitea API.

## Deploy Workflow Porting

Deploy workflows often need secrets and remote side effects. Port them after tests pass.

Guard required secrets explicitly:

```bash
missing=()

for required_var in SPARK_EMAIL SPARK_KEY TIPTAP_PRO_KEY DO_SPACES_KEY DO_SPACES_SECRET DO_SPACES_ENDPOINT DO_SPACES_REGION; do
  if [ -z "${!required_var}" ]; then
    missing+=("$required_var")
  fi
done

if [ "${#missing[@]}" -gt 0 ]; then
  echo "Skipping deploy because required secrets are missing: ${missing[*]}"
  echo "SKIP_DEPLOY=true" >> "$GITHUB_ENV"
fi
```

Gate deploy steps:

```yaml
if: env.SKIP_DEPLOY != 'true'
```

This keeps the default branch green while still making the missing configuration obvious in logs. File follow-up work for the missing secrets.

Do not manually dispatch deploy workflows that upload assets or mutate production unless the user explicitly approves it.

## Verification Checklist

Before declaring cutover complete:

- Gitea repo is not a mirror.
- `origin` points to Gitea.
- `github` remote exists for recovery/reference if desired.
- Default branch is pushed to Gitea.
- Active PR branches are pushed to Gitea.
- Open PRs are recreated in Gitea.
- Repository PRs and Actions are enabled.
- Test workflow passes on PR.
- Test workflow passes on default branch after merge.
- Deploy workflow either succeeds or skips cleanly with a clear missing-secrets message.
- Optional `/review` workflow posts or updates the aggregate OpenCode review comment.
- Runner is online with generic labels.
- Job containers pull the expected image.
- Local branch is synchronized with Gitea:

```bash
git pull --rebase origin {default-branch}
git push origin {default-branch}
git rev-list --left-right --count origin/{default-branch}...{default-branch}
git status --short --branch
```

Expected commit comparison after sync:

```text
0 0
```

## Common 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 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: the workflow passed only a diff to OpenCode 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`.

### OpenCode Review Checkout Is Slow

Cause: `actions/checkout` fetched full history with `fetch-depth: 0`.

Fix: checkout the PR head SHA with `fetch-depth: 1` unless full git history is required.

### 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}
```

## Follow-Up Issues

File explicit follow-up issues for work intentionally deferred during cutover, such as:

- configuring deploy secrets in Gitea
- moving remaining Composer VCS repositories from GitHub to Gitea
- removing obsolete GitHub workflows after Gitea Actions are trusted
- deleting or archiving the GitHub repository after a retention period
- rotating any tokens that were exposed during setup