Docs / Deployments

Official GitHub Action

Report deployment context through the official CrawlDrift Action, a thin wrapper over the same Deployment API contract.

Workflow step

- name: Notify CrawlDrift
  uses: crawldrift/deployment-action@v1
  with:
    project-id: ${{ secrets.CRAWLDRIFT_PROJECT_ID }}
    api-key: ${{ secrets.CRAWLDRIFT_API_KEY }}
    version: ${{ github.ref_name }}
    build-number: ${{ github.run_number }}
    commit-sha: ${{ github.sha }}
    environment: production
    trigger-crawl: true

Idempotency

Use github:{repository_id}:{run_id}:{run_attempt} or github:{deployment_id}. Keep the value stable for retries of the same logical deployment.

Behavior and security

The Action uses the official CLI or container and does not implement a separate deployment protocol.

Secrets remain masked, a failure returns a failed Action status, success exposes the deployment ID output, and the Action uses a pinned compatible CLI or container version.

Shared API contract

Fields, limits and linked crawl behavior

All official clients and compatibility examples submit the same provider-neutral Deployment API contract.

Field	Required	Limit	Purpose
version	One identity field*	100 characters	Release version
buildNumber	One identity field*	100 characters	CI build number
commitSha	One identity field*	100 characters	Commit identity
environment	Optional	50 characters	Deployment environment
externalDeploymentId	Optional	200 characters	Provider deployment identity and idempotency
deployedAt	Optional	Timestamp string	Deployment time
note	Optional	1000 characters	Deployment note
triggerCrawl	Optional	Boolean	Request a linked FULL crawl
rolloutDelaySeconds	Optional	0–3600 seconds	Wait before requesting the linked crawl

* At least one of version, buildNumber or commitSha must be present.

Rollout delay

The request value takes precedence, followed by the Project deployment default, then the platform default. The recommended platform default is 180 seconds; the client does not wait locally.

Collision and quota

An active FULL crawl is not cancelled or replaced. The linked crawl waits for it to finish. Deployment-triggered crawls consume normal crawl-page quota; without quota, the deployment remains recorded and the crawl is BLOCKED_BY_QUOTA.

Retries and timeout

Official clients use a recommended 10-second timeout and may retry network failures, connection resets, and HTTP 502, 503 or 504 with bounded exponential backoff and jitter. Reuse the same idempotency key.

Do not automatically retry most 400, 401, 403, 404, 409 semantic conflict or 422 responses. A timeout does not prove rejection.

Key security

A Deployment key can create deployment records only for its Project. It cannot read Project, Incident or Crawl data, change settings or billing, manage users, start arbitrary crawls or access another Project.

Keys are shown in full once, stored as a cryptographic hash, revocable, replaceable and excluded from logs and diagnostics.

Request limits and target safety

Recommended per-key limits are 10 requests per minute burst and 100 requests per hour sustained; exact limits may be adjusted based on usage.

The API accepts metadata, not callback or arbitrary target URLs. The Project's verified canonical domain remains the crawl target.