fivedevs.com/.gitea/RUNNER_SETUP.md

Gitea Actions runner + Vercel auto-deploy

Pushes to master on Gitea trigger .gitea/workflows/deploy.yml, which type-checks the project and ships to Vercel production.

You only need to do this setup once.

---

1. Enable Actions on the Gitea instance

If you've never used Actions on this Gitea before, enable it in /etc/gitea/app.ini (path varies by install):

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com

Restart Gitea (systemctl restart gitea or however you run it).

Then on the repo in Gitea: Settings → Actions → Enable Actions for this repository.

2. Install a Gitea Actions runner on the Debian box

Gitea ships its own runner binary called act_runner. SSH into your Debian box and:

# Download latest act_runner (check https://gitea.com/gitea/act_runner/releases for newest)
wget -O act_runner https://dl.gitea.com/act_runner/act_runner-linux-amd64
chmod +x act_runner
sudo mv act_runner /usr/local/bin/

# Generate config
act_runner generate-config > config.yaml

# Register with your Gitea instance
# Get a registration token from: https://git.sometimescode.com/-/admin/actions/runners
# (admin level — registers a global runner) OR from the repo settings (repo-scoped)
act_runner register --no-interactive \
  --instance https://git.sometimescode.com \
  --token <REGISTRATION_TOKEN> \
  --name debian-runner \
  --labels ubuntu-latest:docker://node:24-bookworm,self-hosted

# Run as a service (systemd)
sudo cp /usr/local/bin/act_runner /etc/systemd/system/
# (Gitea docs walk through the .service file; or just run in tmux for now)
act_runner daemon

The --labels ubuntu-latest:docker://node:24-bookworm line tells the runner: when a workflow says runs-on: ubuntu-latest, use the node:24-bookworm Docker image. That image has Node 24 + git preinstalled, which is what our workflow needs.

Verify it's online: Gitea → Repo → Settings → Actions → Runners should show one online runner.

3. Get a Vercel API token

1. https://vercel.com/account/tokens
2. Create Token, name it "Gitea fivedevs deploy"
3. Scope: full account (or just the fivedevs project if Vercel supports per-project tokens on your plan)
4. Copy the token — you'll only see it once

4. Add the three secrets to Gitea

Repo → Settings → Secrets → New Secret. Add three:

Secret name	Value
VERCEL_TOKEN	The token from step 3
VERCEL_ORG_ID	team_dvgkcoMxfZwVhSau0vhTeT1I
VERCEL_PROJECT_ID	prj_QVFJhWqmkrzGVP0HBsJJrDxQ96c3

(The org and project IDs come from .vercel/project.json in this repo. They're not sensitive but treating them as secrets keeps the workflow file portable.)

5. Test it

Push any tiny change to master. Within ~10 seconds:

• Gitea: Repo → Actions tab → you should see a workflow run
• After ~2-3 min: Vercel dashboard → fivedevs project → new deployment with the matching commit SHA

If the workflow fails, click into it for logs. Common issues:

• vercel deploy fails with "missing project" → double-check VERCEL_ORG_ID / VERCEL_PROJECT_ID secret values
• pnpm: command not found → runner isn't using a Node-equipped image; revisit step 2's --labels line
• Workflow doesn't trigger at all → repo Settings → Actions isn't enabled

What the workflow does

1. Checks out the repo (full history)
2. Installs pnpm + Node 24 with dependency caching
3. pnpm install --frozen-lockfile
4. tsc --noEmit to fail fast on type errors
5. vercel deploy --prod --yes — uploads source to Vercel, Vercel builds & deploys, returns the prod URL

The whole pipeline is ~2 min on a warm cache.