Migrate Your GitHub Repos to Self-Hosted Gitea on a VPS

In the Gitea interface, go to + → New Organization, pick a name matching your GitHub organisation (this simplifies the remote update later).

Or via the API:

curl -s -X POST https://git.your-domain.com/api/v1/orgs \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"my-org","visibility":"private"}'

Retrieve your repository list (paginated at 100 per page):

curl -s -H "Authorization: token YOUR_GITHUB_TOKEN" \
  "https://api.github.com/orgs/MY_ORG/repos?per_page=100&page=1" \
  | jq -r '.[].name' > repos.txt

The GitHub endpoint used here is GET /repos/{owner}/{repo}/tarball/{ref} for a full archive, and GET /orgs/{org}/repos for the inventory. Check the official documentation at docs.github.com.

The POST /api/v1/repos/migrate endpoint of Gitea API v1 accepts a GitHub source URL (official documentation: gitea.io). For each repository:

while IFS= read -r REPO; do
  curl -s -X POST https://git.your-domain.com/api/v1/repos/migrate \
    -H "Authorization: token YOUR_GITEA_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\n      \\\"clone_addr\\\": \\\"https://github.com/MY_ORG/$REPO\\\",\n      \\\"auth_token\\\": \\\"YOUR_GITHUB_TOKEN\\\",\n      \\\"uid\\\": 2,\n      \\\"repo_name\\\": \\\"$REPO\\\",\n      \\\"issues\\\": true,\n      \\\"labels\\\": true,\n      \\\"milestones\\\": true,\n      \\\"mirror\\\": false\n    }"
done < repos.txt

uid is the numeric ID of your Gitea organisation (visible via GET /api/v1/orgs/my-org). mirror: false means a one-time import — set it to true for continuous sync during the transition period.

For each repository cloned on your workstation:

git remote set-url origin https://git.your-domain.com/my-org/my-repo.git

Or via SSH if you have added your public key in Gitea (Settings → SSH / GPG Keys):

git remote set-url origin [email protected]:my-org/my-repo.git

Verify with git remote -v, then test with git fetch to confirm the remote responds.

In Gitea, for each repository: Settings → Webhooks → Add Webhook. Paste the URL of your CI or third-party service (Slack, Woodpecker CI, etc.), replacing github.com with git.your-domain.com.

The available events (push, pull_request, issues, release) are identical to GitHub's — payloads share the same base structure for most integrations.

Install the official runner on your VPS:

wget -O gitea-runner https://dl.gitea.com/act_runner/latest/act_runner-latest-linux-amd64
chmod +x gitea-runner
./gitea-runner register --no-interactive \
  --instance https://git.your-domain.com \
  --token YOUR_RUNNER_TOKEN \
  --name vps-runner \
  --labels ubuntu-latest:docker://node:20-bullseye
./gitea-runner daemon &

The runner token is generated in Gitea: Site Administration → Runners → Create new Runner Token.

Your existing .github/workflows/*.yml files are understood by gitea-runner without modification for common actions (actions/checkout, actions/setup-node, etc.). Rename .github/workflows/ to .gitea/workflows/ to use Gitea's native path (both are supported, but .gitea/ is the canonical one).

Symptom: git clone [email protected]:… fails with Permission denied (publickey).

Check: in Gitea, Settings → SSH / GPG Keys — the public key you are using must be listed there. Add it if absent (cat ~/.ssh/id_ed25519.pub | pbcopy or xclip).

If the key is present but the error persists, verify that Gitea's SSH port is 22 (or the configured port): ssh -vT [email protected] -p 22 will show the negotiation and Gitea's acceptance message if the key is recognised.

Symptom: git fetch returns fatal: repository 'https://git.your-domain.com/…' not found.

Diagnosis: git remote -v — check that the URL points to your Gitea instance and not github.com. If the URL is correct, log in to the Gitea interface and confirm the repository exists under the correct organisation name. A silently failed POST /api/v1/repos/migrate leaves the repository absent with no error message in the local remote.

Symptom: a git push does not trigger a build in your CI.

Diagnosis: in Gitea, Settings → Webhooks → last delivery: the "Response" field shows the HTTP code returned by your CI. A 404 means the webhook URL points to a non-existent route; a 401 means a misconfigured HMAC secret.

Enable runner debug mode: in the gitea-runner configuration file, set log_level to debug and restart the daemon. Logs will show each event received and the job activation code.