Update an app with a webhook
A webhook token lets a CI pipeline or another external system update an app without an Orchard account. After your pipeline pushes a new image, one POST request with the token rolls the app onto that image. A request without an image restarts the app.
Each token belongs to one app. GitHub webhooks for auto-deploy are separate. The GitHub App handles them.
Create a token
Section titled “Create a token”- Open the app.
- Go to Activity.
- In Webhooks, enter a label, such as
github-actions. - Select Create token.
- Copy the webhook URL and the token. Orchard shows them only once.
The dashboard shows Webhooks for apps that do not build from a GitHub repository. For a GitHub app, use the CLI.
orchard deploy webhook-token create <id> --label github-actionsStore the token in your CI system’s secret store. Anyone with the token can change the app.
Send a request
Section titled “Send a request”Send the token in the Authorization header. The header form keeps the token out of proxy and access logs.
To restart the app:
curl -X POST https://orchard.example.com/apiv1/webhooks/deploy \ -H "Authorization: Bearer $WEBHOOK_TOKEN"To roll an image app onto a new tag:
curl -X POST https://orchard.example.com/apiv1/webhooks/deploy \ -H "Authorization: Bearer $WEBHOOK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"tag": "v1.2.3"}'To roll an image app onto a new image and tag, send {"image": "ghcr.io/org/app", "tag": "sha-abc123"}.
The token also works in the URL, as /apiv1/webhooks/deploy/<token>. The URL that the dashboard shows uses this form.
Behavior
Section titled “Behavior”| Request | App type | Result |
|---|---|---|
No image or tag | Any | Restarts the app on its current image. |
With image or tag | Image | Rolls the app onto the new image. The previous image stays available for rollback. |
With image or tag | GitHub | Returns a 400 error. To rebuild a GitHub app, push to the branch or run orchard deploy rebuild <id>. |
A request returns a 409 error while the app is building. Each token allows 30 requests per minute.
Delete a token
Section titled “Delete a token”Anything still using a deleted token stops working immediately.
- Open the app.
- Go to Activity > Webhooks.
- Select the delete icon on the token.
- Select Delete token.
orchard deploy webhook-token delete <id> <token-id>To rotate a token, create a new one, update the caller, then delete the old one.
A token also stops working if the person who created it loses edit access to the project, or if the API token that created it is revoked or expires. Orchard deletes such a token the next time a request uses it.
Related resources
Section titled “Related resources”- Deploy from an image - Create an app that runs a container image from a registry.
- Roll back an app - Return an app to an earlier release, including the image a webhook replaced.
orchard webhookreference - Send a webhook request from the CLI withorchard webhook deploy.