etcprs/.gitea/workflows/SETUP.md

Gitea Actions — Setup Guide

Prerequisites

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

# 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    <your-runner-token> \
  --name     "droplet-runner" \
  --labels   "ubuntu-latest"

---

1. Generate a deploy key

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

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

# 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:

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:

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:

# 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.