# Gitea Actions — Setup Guide

## Prerequisites

You need a **Gitea runner** registered to your repo or organisation.
If you don't have one yet:

```bash
# On your droplet (or any always-on machine)
# Download the runner binary from your Gitea instance:
# https://git.etcprs.app/-/admin/runners  (site admin)
# or https://git.etcprs.app/<org>/runners (org level)

# Install and register
./gitea-runner register \
  --instance https://git.etcprs.app \
  --token    LSD3GDaXRaU9TUxtrlm8M3hOF72KFipIYchUpqda \
  --name     "droplet-runner" \
  --labels   "ubuntu-latest"
```

---

## 1. Generate a deploy key

Run this **on your local machine** (not the server):

```bash
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/deploy_key -N ""
```

This creates two files:
- `~/.ssh/deploy_key`      — private key (goes into Gitea secret)
- `~/.ssh/deploy_key.pub`  — public key (goes onto the server)

---

## 2. Add the public key to the server

```bash
# Copy the public key to the droplet
ssh-copy-id -i ~/.ssh/deploy_key.pub root@your-droplet-ip

# Or manually:
cat ~/.ssh/deploy_key.pub | ssh root@your-droplet-ip \
  "cat >> ~/.ssh/authorized_keys"
```

Test it works:

```bash
ssh -i ~/.ssh/deploy_key root@your-droplet-ip "echo connected"
```

---

## 3. Add secrets to Gitea

Go to your repo → **Settings → Secrets → Actions** and add:

| Secret name      | Value                                          |
|------------------|------------------------------------------------|
| `DEPLOY_HOST`    | Your droplet IP or hostname                    |
| `DEPLOY_USER`    | `root`                                         |
| `DEPLOY_SSH_KEY` | Contents of `~/.ssh/deploy_key` (private key)  |
| `DEPLOY_PORT`    | `22`                                           |

To get the private key contents:

```bash
cat ~/.ssh/deploy_key
```

Copy the entire output including the `-----BEGIN...-----` and `-----END...-----` lines.

---

## 4. Enable Actions on your repo

In Gitea: **Settings → Repository → Enable Repository Actions** ✓

---

## 5. How it works

### On any branch push or PR → `ci.yml` runs:
1. Install dependencies (`npm ci`)
2. JS syntax check (`node --check` on all `.js` files)
3. Svelte component check (`svelte-check`)
4. Full build (`npm run build`)

If any step fails, the push is marked as failed. No deploy occurs.

### On push to `main` → `deploy.yml` runs:
1. All CI steps above (build must pass first)
2. SSH into the droplet
3. `git pull`
4. `npm install`
5. `npm run build`
6. `chown` to fix file ownership
7. `pm2 reload etc-prs` (zero-downtime reload)

---

## 6. Monitoring

View workflow runs at:
`https://git.etcprs.app/<your-repo>/actions`

---

## Troubleshooting

**"Host key verification failed"**
Add your droplet to known hosts on the runner, or add `StrictHostKeyChecking no`
to the SSH action config (already handled by `appleboy/ssh-action`).

**"pm2: command not found"**
PM2 is installed globally but the SSH session may not have it in PATH. Fix:

```bash
# On the server, find where pm2 is
which pm2   # e.g. /usr/local/bin/pm2

# If needed, symlink it to /usr/bin
ln -s /usr/local/bin/pm2 /usr/bin/pm2
```

**Build fails with missing env vars**
The CI workflow passes dummy env vars — this is intentional. The real vars
are in the PM2 ecosystem config on the server and are never needed at build time.