Skip to main content

​
Required fields

​
deploymentId
string
required
Unique identifier for this deployment from your CI/CD system. Used as the idempotency key — sending the same deploymentId twice updates the existing record.Examples: "gha-12345", "azure-devops-run-67890", "jenkins-build-99999"
​
commitSha
string
required
The git commit SHA that was deployed. This is the key field for DORA metrics — it links the deployment to merged pull requests for lead time calculation.Must be 5-40 hexadecimal characters. Use the full 40-character SHA when possible.
​
environment
string
required
The target environment. Standard values:
  • "production" — used for DORA metric calculations
  • "staging"
  • "development"
  • "preview"
  • "test"
Custom values are accepted. Only "production" deployments contribute to DORA metrics.
​
status
string
required
Current deployment status. Must be one of:
  • "pending" — deployment queued or waiting
  • "in_progress" — currently deploying
  • "success" — deployed successfully
  • "failure" — deployment failed
  • "cancelled" — deployment was cancelled
  • "rolled_back" — deployment was rolled back
​
startedAt
string
required
ISO 8601 timestamp of when the deployment started.Example: "2024-01-15T10:30:00Z"

​
Optional fields

​
completedAt
string
ISO 8601 timestamp of when the deployment completed. Required when status is a terminal state: "success", "failure", "cancelled", or "rolled_back".Used to calculate deployment duration and MTTR.
​
organizationSlug
string
Your organization slug. Optional — the organization is resolved from the API key. If provided, Periscope validates that it matches the key’s organization as a safety check.
​
service
string
Name of the service being deployed. Periscope uses this to:
  • Match the deployment to a repository in your system
  • Group metrics by service (deployment frequency, failure rate)
  • Pair failures with recoveries for MTTR calculation
Can be the repository name, full name (org/repo), or a custom service name.
​
branch
string
The branch that was deployed. Informational — stored for reference but not used in metric calculations.
​
previousCommitSha
string
The commit SHA that was previously deployed to this environment. When provided, Periscope links all PRs merged between previousCommitSha and commitSha to this deployment, enabling accurate lead time for batch deployments.
​
triggeredBy
string
Who or what triggered the deployment. Can be a username, email address, "automation", "schedule", or any custom string.
​
pipelineName
string
Name of the CI/CD pipeline or workflow that performed the deployment. Displayed in the dashboard for context.
​
pipelineUrl
string
URL to view this deployment in your CI/CD system. Displayed as a clickable link in the Periscope dashboard so team members can quickly navigate to the source system.
​
rawPayload
object
The original raw payload from your CI/CD system. If provided, Periscope stores it as-is for future reference. Accepts any JSON object.
​
metadata
object
Custom key-value pairs for any additional data you want to track. Values must be string, number, or boolean.Common uses:
  • "version": "2.1.0" — application version
  • "releaseNotes": "Bug fixes" — release description
  • "featureFlags": "new-checkout-enabled" — active feature flags
  • "rollbackInitiated": true — whether a rollback was triggered

​
Validation rules

RuleDetails
Required fieldsdeploymentId, commitSha, environment, status, startedAt must be non-empty strings
Commit SHA format5-40 hexadecimal characters (regex: /^[a-f0-9]{5,40}$/i)
Status valuesMust be one of the 6 defined statuses
Date formatstartedAt and completedAt must be valid ISO 8601 dates
Terminal statuscompletedAt is required when status is success, failure, cancelled, or rolled_back