Skip to content

Commit 715a79a

Browse files
committed
README updates and fixes
1 parent 3e74ee2 commit 715a79a

5 files changed

Lines changed: 313 additions & 167 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Deploy
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- develop
8+
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Trigger deployment webhook
14+
run: |
15+
curl -X POST \
16+
-H "Authorization: Bearer ${{ secrets.DEPLOY_TOKEN }}" \
17+
-H "Content-Type: application/json" \
18+
"${{ secrets.DEPLOY_WEBHOOK_URL }}"
19+
env:
20+
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
21+
DEPLOY_WEBHOOK_URL: ${{ secrets.DEPLOY_WEBHOOK_URL }}

‎README.md‎

Lines changed: 66 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# wizcoders/deployme
22

3-
Gitea push-to-deploy webhook for Laravel. One endpoint, two independent guards.
3+
Push-to-deploy for Laravel. Two endpoints over one deploy routine: a Gitea webhook
4+
guarded by two independent checks, and a token-only trigger for deploys you fire
5+
by hand or from CI.
46

57
## Install
68

@@ -27,16 +29,28 @@ Everything is per-site and belongs in that site's `.env`, never in the repo:
2729
```
2830
DEPLOY_WEBHOOK_TOKEN= # the Authorization header value Gitea sends
2931
DEPLOY_WEBHOOK_SECRET= # the Gitea webhook Secret, used for the HMAC
32+
DEPLOY_ACTION_TOKEN= # bearer token for the manual POST api/deploy trigger
3033
DEPLOY_BRANCH= # blank = deploy whatever branch is checked out
3134
DEPLOY_REMOTE=origin
35+
DEPLOY_PATH= # blank = the host app's base_path()
3236
DEPLOY_PHP_BIN=php
3337
DEPLOY_COMPOSER_BIN=composer
3438
DEPLOY_TIMEOUT=600
35-
DEPLOY_LOGS_DIRECTORY_PATH="../../deploylogs/"
39+
DEPLOY_LOGS_DIRECTORY_PATH="../deploylogs/"
3640
```
3741

38-
**Both secrets are required.** An empty token or secret means "not set up", and the
39-
endpoint answers 404. Set them *before* pointing a webhook at the site.
42+
Each secret gates its own endpoint, and every one of them is required for that
43+
endpoint to answer: empty means "not set up", which denies with a 404. Set them
44+
*before* pointing anything at the site. A site that only wants the webhook can leave
45+
`DEPLOY_ACTION_TOKEN` blank, and vice versa.
46+
47+
Routing is configurable too, for sites that need to move or silence an endpoint:
48+
49+
```
50+
DEPLOYME_ROUTE_ENABLED=true # false = installed but unroutable
51+
DEPLOYME_ROUTE_PATH=api/deploy/gitea # the webhook
52+
DEPLOYME_ACTION_ROUTE_PATH=api/deploy # the manual trigger
53+
```
4054

4155
## Point Gitea at it
4256

@@ -51,31 +65,61 @@ Repository → Settings → Webhooks → Gitea:
5165
| Authorization Header | `DEPLOY_WEBHOOK_TOKEN` |
5266
| Trigger | Push events |
5367

68+
## Fire a deploy by hand
69+
70+
`POST` to `api/deploy` with the bearer token. No body, no payload:
71+
72+
```bash
73+
curl -X POST https://<site>/api/deploy \
74+
-H "Authorization: Bearer $DEPLOY_ACTION_TOKEN"
75+
```
76+
77+
It runs the same four steps, against the same working copy, holding the same lock as
78+
the webhook — the two endpoints cannot deploy over each other. The branch is resolved
79+
the same way as well: `DEPLOY_BRANCH` if set, otherwise whatever is checked out.
80+
81+
The token is **deliberately not** `DEPLOY_WEBHOOK_TOKEN`. This endpoint has no payload
82+
and therefore no HMAC to check, so that single token is the only thing standing in
83+
front of a shell; it is a weaker guard than the webhook's and must be rotatable on its
84+
own. Give it a long random value:
85+
86+
```bash
87+
php -r 'echo bin2hex(random_bytes(32)), PHP_EOL;'
88+
```
89+
5490
## How the guard works
5591

56-
Two checks, both required, both constant-time:
92+
On the webhook (`api/deploy/gitea`), two checks, both required, both constant-time:
5793

5894
1. **`Authorization` header** against `deployme.token` — proves who is calling.
5995
2. **`X-Gitea-Signature`** against `hash_hmac('sha256', <raw body>, deployme.secret)`
6096
— proves the payload was not rewritten in transit.
6197

62-
Either one alone is not enough. Every rejection is a bare `404` so the endpoint does
63-
not advertise itself to a scanner, and the route is rate limited.
98+
Either one alone is not enough. The manual trigger has only check 1, against
99+
`deployme.action_token` — there is no body to sign.
100+
101+
Both routes reject with a bare `404` so they do not advertise themselves to a scanner,
102+
both compare with `hash_equals()`, and both are rate limited to 10 requests a minute.
64103

65104
## Responses
66105

67-
| Status | Meaning |
68-
|---|---|
69-
| `200 deployed` | All four steps ran and succeeded. |
70-
| `200 ignored` | Authentic call, but not for this site — wrong branch, or not a push. Deliberately 2xx: a non-2xx makes Gitea mark the delivery failed and retry it. |
71-
| `200 pong` | Gitea's `ping`, sent once when the webhook is saved. |
72-
| `404` | Failed either guard. |
73-
| `409 busy` | A deploy is already running. Concurrency is held off with a non-blocking `flock`. |
74-
| `500 failed` | A step failed. The run **stops at the first failure** rather than pressing on. |
106+
Both endpoints answer with a `status` and, on a run, a `steps` array carrying each
107+
command's exit code.
108+
109+
| Status | Endpoint | Meaning |
110+
|---|---|---|
111+
| `200 deployed` | both | All four steps ran and exited zero. |
112+
| `200 ignored` | webhook | Authentic call, but not for this site — wrong branch, or not a push. Deliberately 2xx: a non-2xx makes Gitea mark the delivery failed and retry it. |
113+
| `200 pong` | webhook | Gitea's `ping`, sent once when the webhook is saved. |
114+
| `400 error` | trigger | Detached HEAD and no `DEPLOY_BRANCH`, so there is no branch to pull. |
115+
| `404` | both | Failed a guard. |
116+
| `409 busy` | both | A deploy is already running. Concurrency is held off across *both* endpoints with a single non-blocking `flock`. |
117+
| `500 failed` | both | A step exited non-zero. The run **stops at the first failure** rather than pressing on; `steps` shows how far it got. |
75118

76119
## What it runs
77120

78-
In the repository root, in order, stopping on the first non-zero exit:
121+
Both endpoints run the same thing, in the repository root, in order, stopping on the
122+
first non-zero exit:
79123

80124
```
81125
git pull <remote> <branch>
@@ -84,6 +128,10 @@ php artisan migrate --force
84128
php artisan optimize
85129
```
86130

131+
`--force` and `--no-interaction` are not optional: without them `migrate` refuses to
132+
run unattended in production and `composer` can block on a prompt until the step times
133+
out. `DEPLOY_TIMEOUT` caps each step individually.
134+
87135
`composer` and `php` must be on the **web user's** PATH, which is often not the PATH
88136
you get over SSH. Set `DEPLOY_COMPOSER_BIN` / `DEPLOY_PHP_BIN` to absolute paths if a
89137
step exits non-zero with no output.
@@ -92,7 +140,8 @@ step exits non-zero with no output.
92140

93141
`DEPLOY_BRANCH` wins if set. Otherwise the branch is read from `.git/HEAD` directly —
94142
no `exec()`, so it works on hosts where shell functions are disabled. A detached HEAD
95-
yields no branch and the push is ignored rather than guessed at.
143+
yields no branch: the push is ignored rather than guessed at, and the manual trigger
144+
answers `400`.
96145

97146
## Not a replacement for `deploy.php`
98147

‎config/deployme.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@
2424
'route' => [
2525
'enabled' => (bool) env('DEPLOYME_ROUTE_ENABLED', true),
2626
'path' => env('DEPLOYME_ROUTE_PATH', 'api/deploy/gitea'),
27+
28+
// The token-only trigger. Configurable so it cannot collide with `path`
29+
// on a site that has moved the webhook.
30+
'action_path' => env('DEPLOYME_ACTION_ROUTE_PATH', 'api/deploy'),
31+
2732
'middleware' => ['api', 'throttle:10,1'],
2833
],
2934

@@ -42,6 +47,12 @@
4247
// Gitea webhook "Secret" — drives the X-Gitea-Signature HMAC-SHA256.
4348
'secret' => env('DEPLOY_WEBHOOK_SECRET', ''),
4449

50+
// Bearer token for the token-only trigger (POST api/deploy). Deliberately
51+
// separate from `token`: that endpoint has no HMAC behind it, so it is a
52+
// weaker guard and must be rotatable without touching the webhook. Empty
53+
// means "not set up", and the trigger answers 404.
54+
'action_token' => env('DEPLOY_ACTION_TOKEN', ''),
55+
4556
/*
4657
|--------------------------------------------------------------------------
4758
| What to deploy

‎routes/api.php‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,13 @@
1717
->name('deployme.gitea');
1818

1919
/*
20-
| Simple token-based deployment trigger.
20+
| Simple token-based deployment trigger, for deploys fired by hand or by CI.
2121
|
22-
| Requires Authorization header with Bearer token.
23-
| Token is configured in deployme.token (usually from DEPLOY_WEBHOOK_TOKEN env).
22+
| Requires an Authorization header carrying the bearer token configured in
23+
| deployme.action_token (usually from the DEPLOY_ACTION_TOKEN env). That is a
24+
| different secret from the webhook's — this endpoint has no HMAC behind it.
2425
*/
2526

26-
Route::post('api/deploy', [DeploymentActionController::class, 'deploy'])
27+
Route::post(config('deployme.route.action_path', 'api/deploy'), [DeploymentActionController::class, 'deploy'])
2728
->middleware(config('deployme.route.middleware', ['api', 'throttle:10,1']))
2829
->name('deployme.action');

0 commit comments

Comments
 (0)