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

```text
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:

```bash
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.