Docs / Deployments

Official CrawlDrift deployment container

Run the stateless, one-shot CrawlDrift CLI image inside a compatible CI job.

Run the container

docker run --rm \
  -e CRAWLDRIFT_API_KEY="$CRAWLDRIFT_API_KEY" \
  -e CRAWLDRIFT_PROJECT_ID="$CRAWLDRIFT_PROJECT_ID" \
  -e CRAWLDRIFT_VERSION="$APP_VERSION" \
  -e CRAWLDRIFT_BUILD_NUMBER="$BUILD_NUMBER" \
  -e CRAWLDRIFT_COMMIT_SHA="$COMMIT_SHA" \
  -e CRAWLDRIFT_ENVIRONMENT="production" \
  -e CRAWLDRIFT_TRIGGER_CRAWL="true" \
  ghcr.io/crawldrift/deployment:v1

Image and command

The default command is crawldrift deployment notify. The image exits after sending the deployment; it is not a daemon.

CI examples may use the v1 tag. Exact 1.0.0 and 1.0 tags are defined, and security-sensitive usage should pin an exact tag or digest. Do not rely only on latest.

Container security

Non-root, minimal runtime with no baked credentials
No persistent filesystem requirement, inbound port or background process
Read-only compatible and stateless
Vulnerability scanning, SBOM generation and signed release artifacts where practical

Logging

Logs must not include the API key, Authorization header, full secret environment variables or response headers containing secrets.

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.