Deploy triggers

A deploy trigger is a private URL your pipeline calls to redeploy one service. It’s the piece that connects your existing CI/CD to Helicarrier: build and publish however you like, then POST to the URL and your new version rolls out.

Unlike an API key, a trigger can do exactly one thing — redeploy the service it belongs to. It can’t read your data, touch other services, or change your account. That makes it safe to paste into a pipeline.

Note

Not to be confused with deploy hooks, which run JavaScript before or after a deploy to gate or verify it. A deploy trigger starts a deploy from outside; a deploy hook runs during one.

Create one

1. Open your service and go to Agents & API.
2. Under Deploy trigger, choose Create deploy trigger.
3. Copy the URL — it’s shown only once.

If you lose it, choose Regenerate for a new one. The previous URL stops working the moment you do.

Use it

From anywhere that can make an HTTP request:

curl -X POST https://app.helicarrier.xyz/api/deploy-triggers/helitrig_xxxxxxxx

A successful call returns 202 with the new deployment’s id:

{ "deploymentId": "d077ae7e-…", "service": "api" }

The deploy then runs exactly as it would from the dashboard — same build, health checks, and zero-downtime switch — and appears in your deploy history marked as cicd.

GitHub Actions

Store the URL as a repository secret (e.g. HELI_DEPLOY_TRIGGER) and add a final step:

- name: Deploy to Helicarrier
  run: curl -fsS -X POST "${{ secrets.HELI_DEPLOY_TRIGGER }}"

Deploying a branch, tag or commit

If your service builds from Git, send a ref and that’s what gets built — no merge to main, and without changing what the service tracks:

# release pipeline: build the tag you just pushed
curl -X POST "$HELI_DEPLOY_TRIGGER" \
  -H 'Content-Type: application/json' \
  -d '{"ref":"v1.2.3"}'

ref accepts a branch, a tag, or a commit SHA. The deploy is a one-off: your service keeps tracking its usual branch, so auto-deploy carries on as before. The deploy history records what was built (cicd @v1.2.3).

In GitHub Actions, deploying on a tag push:

on:
  push:
    tags: ["v*"]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy the tag to Helicarrier
        run: |
          curl -fsS -X POST "${{ secrets.HELI_DEPLOY_TRIGGER }}" \
            -H 'Content-Type: application/json' \
            -d "{\"ref\":\"${GITHUB_REF_NAME}\"}"

Deploying a new image

If your service runs a prebuilt image, you have two options — and neither needs you to edit anything in the dashboard.

Use a moving tag (simplest). Point the service at a tag your pipeline overwrites, like :latest or :main. Helicarrier re-pulls the image on every deploy, so calling the trigger always picks up what you just pushed:

docker push ghcr.io/acme/api:latest
curl -X POST "$HELI_DEPLOY_TRIGGER"

Use immutable tags. If each build gets its own tag or digest, send it with the request and the service is repointed before the deploy runs:

docker push ghcr.io/acme/api:v1.2.3
curl -X POST "$HELI_DEPLOY_TRIGGER" \
  -H 'Content-Type: application/json' \
  -d '{"image":"ghcr.io/acme/api:v1.2.3"}'

Private registries keep working — the credentials saved on the service are used for the pull.

Keeping it safe

• Treat the URL like a password: store it as a secret, never commit it.
• It’s stored hashed, so nobody — including us — can show it to you again after creation.
• Regenerate replaces it instantly; Revoke turns it off entirely.
• Deleting the service deletes its trigger.
• Triggers are rate-limited per source IP, so a runaway pipeline can’t hammer the platform.

Responses

Code	Meaning
202	Accepted — the deploy is queued.
400	The image you sent isn’t a valid reference, or the service doesn’t run an image.
404	Unknown trigger — it was revoked, regenerated, or the service no longer exists.
409	A deploy is already running for this service, or the account is suspended.
429	Too many requests from this IP — retry shortly.