Docs / Deployments
Jenkins compatibility example
Run the official CrawlDrift container from Jenkins. This is generic CI/CD compatibility, not a native Jenkins integration.
All deployment documentationPipeline step
docker.image('ghcr.io/crawldrift/deployment:v1').inside {
sh 'crawldrift deployment notify'
}Credentials
Provide secrets through Jenkins credentials. Keep the Project-scoped Deployment key out of logs.
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.