59 lines
2.0 KiB
Markdown
59 lines
2.0 KiB
Markdown
# 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.
|