template-script

Template for XeplosionGames infrastructure, configuration, and script-based service repos. Use this for nginx configs, systemctl services, Docker compose deployments, and any repo where the primary artifact is configuration or shell scripts rather than compiled code.

---

Creating a repo from this template

1. Click Use this template on Forgejo
2. Name your repo using the node- prefix for VPS services or hub- prefix for hub services (e.g. node-nginx, hub-zulip)
3. Follow the setup checklist below

---

Setup checklist

• Set DEPLOY_TARGET secret (vps or hub) in Settings → Secrets
• Set RELEASE_TOKEN secret in Settings → Secrets
• Fill in xegames.config.yml — set deploy.target and healthcheck.endpoint
• Implement scripts/validate.sh for your service
• Implement scripts/service-start.sh for your service
• Implement scripts/healthcheck.sh if this is an HTTP service
• Update cron expression in .forgejo/workflows/healthcheck.yml to match healthcheck.interval
• Clone repo on target server as cicd user
• Add sudoers entry on target server if systemctl access is needed
• Run create-project.sh from XeplosionGames/.forgejo to seed project board
• Push to main and verify CI passes
• Enable notify.zulip: true once service is stable

---

Code style

Shell scripts in this repo use the following conventions:

• Indent with 2 spaces
• Always quote variables: "$VAR" not $VAR
• Always use #!/bin/bash shebang
• set -euo pipefail at the top of any non-stub script

ci.format_check is currently disabled pending org-wide shell style conventions being defined. Tracked in XeplosionGames/org.

---

Scripts

Each script in scripts/ is a stub. Implement the body for your service — see the comments inside each file for examples.

Script	Required	Called by
service-start.sh	✅	deploy-production.yml, deploy-test.yml, rollback.yml
validate.sh	✅	ci-script.yml
healthcheck.sh	✅ if HTTP	All deploy workflows, healthcheck.yml
service-stop.sh	optional	Manual / future workflows
build.sh	optional	release.yml

---

Workflows

Workflow	Trigger	Purpose
ci-script.yml	Every push / PR	Runs scripts/validate.sh
deploy-production.yml	Push to main	Deploy to production server
deploy-test.yml	Push to dev	Deploy to test server (if enabled)
rollback.yml	Manual / auto	Roll back to a previous commit
healthcheck.yml	Scheduled	Periodic service health check
release.yml	Tag push v*	Generate release notes + attach artifacts

---

Branch structure

Branch	Purpose
main	Production-ready, auto-deploys to production
dev	Active development, auto-deploys to test (if enabled)
feature/*	Short-lived feature branches, PR to dev or main
hotfix/*	Urgent fixes off main, PR to both main and dev

Simple repos with no test environment only need main.