ForgeFlow/docs/DEPLOYMENT_SETUP.md

Deployment setup guide

This guide connects one Gitea repository to one server environment without giving the desktop arbitrary shell access.

1. Add fixed workflows

Copy these examples into the repository:

examples/gitea-actions/deploy.yml   -> .gitea/workflows/deploy.yml
examples/gitea-actions/rollback.yml -> .gitea/workflows/rollback.yml

Change the runner label to the label registered for the target environment.

2. Install the allowlisted server entry point

Copy examples/server/forgeflow-deploy to /usr/local/bin/forgeflow-deploy, customize its repository/environment allowlist and make it root-owned:

sudo install -o root -g root -m 0755 forgeflow-deploy /usr/local/bin/forgeflow-deploy

Grant the runner account permission to execute only this entry point where elevation is needed. Do not grant unrestricted shell or Docker administration merely for ForgeFlow.

3. Expose deployment status

The example script writes an atomic JSON document beneath /var/lib/forgeflow-status. Serve the appropriate file at a fixed HTTPS URL, for example with examples/server/nginx-forgeflow-status.conf.

See STATUS_ENDPOINT.md for the contract.

4. Configure the ForgeFlow profile

Open the repository, choose Deployments and add an environment with:

• Name: Production or Staging.
• Environment: the fixed workflow input.
• Branch: usually main.
• Workflow file: deploy.yml.
• Rollback workflow: rollback.yml.
• Status URL: the JSON endpoint.
• Healthcheck URL: the application health endpoint.
• Confirmation: enabled for production.

5. Validate the complete path

Test these scenarios before relying on production:

1. Clean commit and push.
2. Successful deployment to the exact SHA.
3. Gitea runner failure.
4. Application healthcheck failure.
5. Server reports the wrong SHA.
6. Second deployment while the lock is held.
7. Rollback to the recorded previous SHA.
8. Token without sufficient permissions.

Keep a manual recovery path documented even after rollback works.