diff --git a/README.md b/README.md
index 91b4958..da14ca7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,36 @@
 # quay-deployment
 
-A composite action for deploying to a quay instance
\ No newline at end of file
+A Gitea Actions composite action that triggers a deployment on a [Quay](https://git.fish/Quay) instance via its API.
+
+## Usage
+
+```yaml
+- uses: https://git.fish/quay/quay-deployment@v1
+  with:
+    BASE_URL: ${{ vars.QUAY_BASE_URL }}
+    SITE_ID: ${{ vars.QUAY_SITE_ID }}
+    DEPLOY_TOKEN: ${{ secrets.QUAY_DEPLOY_TOKEN }}
+```
+
+## Inputs
+
+| Input | Required | Description |
+|---|---|---|
+| `BASE_URL` | Yes | Base URL of your Quay instance (e.g. `https://quay.example.com`) |
+| `SITE_ID` | Yes | UUID of the site to deploy |
+| `DEPLOY_TOKEN` | Yes | Deploy token for the site |
+
+You get the site ID and deploy token when creating the site in Quay.
+
+## How it works
+
+The action sends a `POST` request to `{BASE_URL}/api/v1/deploy?site={SITE_ID}` with the provided deploy token. If the response status is outside the 2xx range, the action fails and prints the response body.
+
+## Notes
+
+- `BASE_URL` can be provided with or without a trailing slash, and with or without a protocol prefix. `https://` is assumed if no protocol is given.
+- Store `DEPLOY_TOKEN` as an encrypted secret, not a plain variable.
+
+## License
+
+MIT
\ No newline at end of file