gitea

---
name: gitea
description: Use when managing ephemeral Gitea Docker environments, mirroring GitHub repos for isolated work, or promoting changes back to GitHub as PRs. Triggers on gitea, ephemeral git, isolated git environment, git sandbox for experiments/testing/demos, mirror repo, promote branch, disposable git server with issues/PRs/API access.
user-invocable: true
---

# Gitea Ephemeral Environments

`amplifier-gitea` is a CLI for on-demand, ephemeral Gitea Docker containers. All commands output JSON to stdout.

## Prerequisites Check

Before any gitea operation, verify the environment:

```bash
# 1. Is the CLI installed?
which amplifier-gitea

# 2. Is Docker available and running?
which docker && docker info > /dev/null 2>&1 && echo "Docker OK" || echo "Docker NOT running"
```

If `amplifier-gitea` is not found:
```bash
uv tool install git+https://github.com/microsoft/amplifier-bundle-gitea@main
```

If Docker is not running:
- **Linux**: `sudo systemctl start docker`
- **macOS**: `open -a Docker`
- **WSL**: Start Docker Desktop on Windows, ensure WSL integration is enabled

**If prerequisites are missing, report clearly and stop. Do not attempt workarounds.**

## Documentation

For overview, quick start, installation, and workflow examples:

```
read_file("@gitea:README.md")
```

For complete CLI reference with all flags, output schemas, and Gitea API examples:

```
read_file("@gitea:docs/api_reference.md")
```

For development setup, testing, and design decisions:

```
read_file("@gitea:docs/development.md")
```

## Key Details

### Admin Credentials

Every environment is created with an `admin` account and a unique random password returned by `create`. The service binds to `127.0.0.1` by default; pass `--bind-address 0.0.0.0` only when remote access is required. The Gitea web UI is accessible at `http://localhost:<port>` and the Swagger API docs at `http://localhost:<port>/swagger`.

### Mirroring Performance

By default `mirror-from-github` copies only git content (full history + all branches) and skips metadata. This is fast -- typically a few seconds.

Issues and PRs are the expensive part. Enabling `--include-issues --include-prs` can take several minutes depending on the repo size. Only opt in when you actually need it.

### GitHub Token Resolution

GitHub sync commands (`mirror-from-github`, `promote-to-github`) resolve tokens in this order:
1. `--github-token` flag (explicit)
2. `GH_TOKEN` environment variable
3. `gh auth token` CLI command

If the user has `gh auth login` done, no extra token configuration is needed.

## Deploying Local Changes Without Committing

To test a local repo's working tree (committed + staged + unstaged + untracked + deletions) through a Gitea mirror without committing or staging anything in the source repo, snapshot it into a throwaway clone and push from there. Use this when the mirror must reflect your exact local state but you must not mutate the source repo (no `git add`/`commit`/`stash` in it).

First make sure the repo exists in Gitea (`mirror-from-github <id> --github-repo ...` or create an empty repo), then:

```bash
PORT=...   # from `amplifier-gitea status <id>`
TOKEN=...  # from `amplifier-gitea token <id>`
SNAP="$(mktemp -d)/<repo-name>"
git clone --local --no-hardlinks "<local-repo>" "$SNAP"
# overlay staged + unstaged + untracked (non-ignored) files from the working tree
( cd "<local-repo>" && git ls-files -z --cached --modified --others --exclude-standard ) \
  | rsync -a --files-from=- --from0 "<local-repo>/" "$SNAP/"
# mirror tracked-file deletions
( cd "<local-repo>" && git ls-files -z --deleted ) \
  | ( cd "$SNAP" && xargs -0 --no-run-if-empty rm -f )
# single throwaway commit IN THE SNAPSHOT, then force-push to the mirror
cd "$SNAP"
git -c user.email=snapshot@local -c user.name="Gitea Snapshot" add -A
git -c user.email=snapshot@local -c user.name="Gitea Snapshot" commit --allow-empty -m "working-tree snapshot"
git -c credential.helper= push --force \
  "http://admin:$TOKEN@localhost:$PORT/admin/<repo-name>.git" HEAD:refs/heads/main
```

All `git add`/`commit` happens only in the temp snapshot, never in the source repo. If snapshotting fails, abort -- never fall back to operating on the source working tree.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `command not found: amplifier-gitea` | `uv tool install git+https://github.com/microsoft/amplifier-bundle-gitea@main` |
| `Cannot connect to the Docker daemon` | Start Docker: `sudo systemctl start docker` (Linux) or open Docker Desktop (macOS/Windows) |
| `port is already allocated` | Choose a different `--port` value, or `amplifier-gitea list` to find existing environments |
| `mirror-from-github` fails on private repo | Pass `--github-token` or ensure `gh auth login` is done |
| Token lost after `create` | Run `amplifier-gitea token <id>` to generate a new one |
| `promote-to-github` 404 error | Verify `--github-repo` is in `owner/repo` format (not a full URL) |
| `No GitHub token found` | Run `gh auth login`, or set `GH_TOKEN`, or pass `--github-token` |
| `Branch already exists` on promote | The `--github-branch` already exists on the target repo. Use a different branch name. |