Skip to content

jackson2w/claude-code-skills / forgejo-deployment

forgejo-deployment

Unverified

This skill should be used when installing or debugging a self-hosted Forgejo (Gitea fork) git server as a native binary + systemd service — not Docker. Covers the three required secrets (SECRET_KEY/INTERNAL_TOKEN/JWT_SECRET) and the permission-denied crash-loop from a locked-down config file, unattended install without exposing the web setup wizard, why Forgejo's built-in git-SSH server needs firewall-level scoping instead of an app-level bind address, a non-obvious API scope requirement for repo deletion, and Vultr Block Storage's region-locking. Trigger phrases include "forgejo install", "forgejo systemd", "forgejo app.ini", "JWT_SECRET failed loading", "save oauth2.JWT_SECRET failed", "forgejo not supposed to be run as root", "forgejo admin user create", "forgejo random-password", "forgejo generate secret", "forgejo INSTALL_LOCK", "forgejo git-ssh port", "forgejo delete repo API 403", "write:user scope forgejo", "vultr block storage wrong region", "no active instances available in this region", "vultr NVMe block storage not available".

Status note (2026-08-24): the dfw instance this skill documents was decommissioned — it was live 2026-08-16 through 2026-08-24 but had zero repos, pushes, clones, or logins in its entire log history (every real repo went to GitHub instead). Torn down: service, binary, git user, Tailscale Serve mapping, ufw rules, and the dedicated Vultr Block Storage volume all removed. See project_dfw_vultr_buildout memory for the full decommission record. This skill's technical content below is kept as-is for any future redeploy — nothing here needs correcting, it just isn't live right now.

Version — verify, don't assume

Check forgejo.org/releases (or code.forgejo.org/forgejo/forgejo/releases) for the current stable tag before installing — don't reuse a version number from a prior session/training data. Download the binary and its .sha256 file, verify before installing:

VERSION="16.0.2"  # confirm current at forgejo.org/releases
wget -q "https://code.forgejo.org/forgejo/forgejo/releases/download/v${VERSION}/forgejo-${VERSION}-linux-amd64"
wget -q "https://code.forgejo.org/forgejo/forgejo/releases/download/v${VERSION}/forgejo-${VERSION}-linux-amd64.sha256"
sha256sum -c "forgejo-${VERSION}-linux-amd64.sha256"
sudo install -m 755 "forgejo-${VERSION}-linux-amd64" /usr/local/bin/forgejo

Three secrets are required, not two

app.ini's [security] section needs SECRET_KEY and INTERNAL_TOKEN — but oauth2 also needs its own [oauth2] JWT_SECRET, easy to miss since it's a separate config section and the docs don't always group all three together. Generate all three the same way, redirected straight to a file (never printed — same discipline as any other credential):

sudo -u git bash -c '/usr/local/bin/forgejo generate secret SECRET_KEY > /tmp/secret_key.txt'
sudo -u git bash -c '/usr/local/bin/forgejo generate secret INTERNAL_TOKEN > /tmp/internal_token.txt'
sudo -u git bash -c '/usr/local/bin/forgejo generate secret JWT_SECRET > /tmp/jwt_secret.txt'

(wc -c the files to confirm non-empty — wc -l can misleadingly report 0 since these values have no trailing newline, not because the file is empty.)

If JWT_SECRET is left unset, Forgejo doesn't fail cleanly — it tries to auto-generate one and write it back into app.ini on every startup:

[oauth2] JWT_SECRET or JWT_SECRET_URI failed loading: invalid base64 decoded length: 0, expects: 32 - creating new key
[F] save oauth2.JWT_SECRET failed: failed to save "/etc/forgejo/app.ini": open /etc/forgejo/app.ini: permission denied

If app.ini is deliberately locked down (e.g. root:git 640 so the running git user can read but not write its own config — the correct posture, not a bug) this write-back fails and the service crash-loops (Start request repeated too quickly after 5 rapid restarts). Fix: generate JWT_SECRET explicitly upfront like the other two, append it under [oauth2] before first start, never rely on the auto-write-back path.

Unattended install — never expose the setup wizard

Set INSTALL_LOCK = true in app.ini from the start (with DB_TYPE/PATH and all three secrets already filled in) so the interactive web installer never runs, not even for a moment. Create the first (admin) account via CLI instead of the web wizard:

sudo -u git bash -c 'export GITEA_WORK_DIR=<data-dir>; /usr/local/bin/forgejo admin user create \
  --config /etc/forgejo/app.ini --admin --username <user> --email <email> \
  --random-password > /tmp/forgejo-admin-create.log 2>&1'

--password-file is not a valid flag on this CLI (only --password for a literal value or --random-password to have Forgejo generate one) — redirect --random-password's output to a file rather than letting it print to a shared terminal/tool output, then have the actual account owner retrieve and delete that file themselves.

Git-SSH: the built-in server ignores HTTP_ADDR-style restriction

START_SSH_SERVER = true + SSH_PORT/SSH_LISTEN_PORT (use a non-standard port like 2222 if the host already runs a real system sshd on 22 for admin access — avoids fighting with the system sshd's authorized_keys command-wrapping approach for a second SSH identity) binds to all interfaces regardless of what HTTP_ADDR is set to for the web UI — there is no equivalent bind-address setting for the SSH listener. Reachability must be scoped at the firewall layer instead:

sudo ufw allow in on tailscale0 to any port 2222 proto tcp comment 'forgejo git-ssh, tailnet only'

Verify both directions (same discipline as any other Tailscale-scoped service): refused from outside the tailnet (nc -zv <public-ip> 2222 times out), reachable via the Tailscale IP (nc -zv <tailscale-ip> 2222 succeeds). Clone URL when the SSH port isn't 22: ssh://git@<domain>:<ssh-port>/<owner>/<repo>.git (the ssh:// scheme + explicit port, not the short git@host:owner/repo.git form, which assumes port 22).

SSH clone/push needs a public key registered to the account first (Settings → SSH/GPG Keys → "Manage SSH keys" section specifically, not the GPG one right below it — easy to click the wrong "Add key" button since both sections look identical at a glance) — there's no anonymous SSH access even to a repo the same user owns.

API gotcha: deleting a repo needs write:user scope, not write:repository

A token minted with --scopes write:repository gets a 403 calling DELETE /api/v1/repos/{owner}/{repo}:

{"message":"token does not have at least one of required scope(s): [write:user]"}

Mint cleanup/admin tokens with --scopes write:repository,write:user if repo deletion is part of what they'll be used for. Also: there is no forgejo admin user delete-access-token CLI command (only generate-access-token exists) — revoke a token via the web UI (Settings → Applications) or the API's own token-management endpoint; a short-lived cleanup token left over after a one-off script isn't a real risk (scoped to one account) but isn't self-cleaning either.

Running as root fails fast and loud (this is correct)

forgejo admin user list (or any subcommand) run as root instead of the configured RUN_USER refuses outright: Forgejo is not supposed to be run as root ... use setcap and cap_net_bind_service. Always sudo -u <run-user> ... for CLI operations, matching whatever RUN_USER/User= the systemd service itself uses.

Vultr Block Storage is region-locked — check before creating, not after

A Block Storage volume can only attach to an instance in the same Vultr datacenter/region. Symptom if mismatched: the dashboard's attach flow shows "No active instances available in this region to attach to" with no instance picker at all — not an error on the instance, a genuine "this volume physically cannot go here" state with no workaround short of destroying and recreating in the right region.

Two things worth confirming before creating the volume, not after:

  • The instance's actual region (Vultr's dfw location code is Dallas — a hostname that looks like a location code is a strong hint, but confirm rather than assume).
  • NVMe Block Storage isn't offered in every region — it may simply not appear as a creatable option for the instance's actual datacenter. HDD Block Storage has broader regional availability and is ~4x cheaper per GB ($1/40GB vs $1/10GB for NVMe) — a reasonable choice by default for a single-user, low-traffic workload where disk latency won't be the bottleneck (network/protocol overhead dominates for occasional personal use), not just a fallback when NVMe isn't available.

Volumes can be resized up later (dashboard, CLI, or Terraform) but never shrunk — no need to overprovision "just in case" up front if growing later is genuinely just a resize + filesystem extend with no data migration.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall