Integration guide
2 min read
Report deployments from your pipeline
Send signed delivery events without giving Specita access to your hosting provider.
Before you start
- An app with a platform component.
- Owner or admin access to generate its reporting key.
- A pipeline that can run Node.js and store secrets.
Set up the connection
Generate a reporting key
Open Integrations → Deployment reporting. Select the component and generate its key. Save the one-time secret and endpoint in your CI secret store.
Download the reporter
Use the dependency-free reporter from the setup dialog or /shipos-report.mjs. Keep the existing SHIPOS environment-variable names; they are compatibility identifiers.
Create the event
After the provider reports a delivery result, write an event with environment, version, status, provider, externalId, and deployedAt. Include the full commit SHA when known. Give each delivery attempt a stable unique externalId.
Send and preserve retries
Run the reporter with the event file and the endpoint/key from CI secrets. Retry with exactly the same event body and externalId. Changed data under an existing externalId returns 409.
Rotate before expiry
Reporting keys expire after 90 days. Rotation immediately invalidates the previous key; update the pipeline’s secret before its next report.
# Inject these through your CI secret store, not source code.
# SHIPOS_DEPLOYMENT_ENDPOINT
# SHIPOS_DEPLOYMENT_SECRET
node shipos-report.mjs deployment.jsonCheck your setup
- The component shows a last-reported timestamp.
- The event appears under the correct platform and environment in Deployments.
- Replaying the unchanged event does not create another delivery.
Troubleshooting
Signature rejected
Check the endpoint, key, key expiry, and runner clock. The signature includes a timestamp and the exact JSON bytes; the acceptance window is five minutes.
409 on retry
The externalId already identifies an event with different data. Use the original event for a retry, or a new externalId for a genuinely new attempt.
Hosting provider not listed
Run the reporter from your existing pipeline. Deployment reporting is provider-neutral, not a native hosting-provider synchronization adapter.
Credential safety
Use HTTPS outside loopback development. The reporter refuses redirects. Never put the reporting secret in the event JSON, logs, or a public repository.