Delivery

The Delivery page shows how your work reaches your users. Connect Vercel or Coolify and every deploy appears under Ship → Delivery in the project sidebar, with its commit, its outcome and its build log. Each deploy is linked to the tasks it shipped, so finished work shows on its item as live and ready to check, and nobody spends time testing work that never made it out.

DevSpec learns about deploys through webhooks: your hosting platform sends DevSpec a message each time a deploy starts, succeeds or fails. You set that up once per deployment target.

What the Delivery page shows

Open Ship → Delivery in the project sidebar.

Until a deployment target is connected, the page shows Configure deployment targets, which takes you to the setup page. Once a target exists but no deploy has arrived yet, it shows a checklist for each target: Webhook URL, Webhook secret and API token, each marked as configured or missing, with Test webhook and Verify connection buttons.

After the first deploy arrives, the page shows:

• A status strip with the number of deploys that Succeeded and Failed in the period you're looking at, and All systems operational when nothing is failing.
• Filters: All, Succeeded, Failed or Building; a period of Last 24h, Last 7 days (the default), Last 30 days or All time; a target picker when the project has more than one target; and Tasks only, which hides deploys that aren't linked to an item.
• The deploy list, 25 to a page and refreshed every 30 seconds. Each deployment has its own expandable card showing the status (Succeeded, Failed, Building or Queued), target, commit, linked pull requests, time and linked work, along with the agent or commit author when recorded.

Open a deployment to see its commit, linked work, checks, build log and earlier attempts. Select the commit to inspect it, or open a linked task to see its implementation and verification. Discuss starts or continues a conversation about the work, and Agent command lets you hand it to an agent.

A failed deploy that DevSpec diagnosed also shows AI analysis. If a later deploy to the same target succeeded, the earlier failure is labeled Later deployment succeeded so your team can see that the target has already recovered.

While a deploy is building or has failed, and for a short while after one succeeds, a deployment status also appears in the app header.

Connect a deployment target

A deployment target is one app on your hosting platform that deploys one of your repositories. DevSpec supports Vercel and Coolify. You need to be a Maintainer on the project, and project settings are available on desktop.

1. Make sure the repository has a Tracking branch set in Project settings → Repositories. A deployment target uses that branch to match deploys.
2. Go to Project settings → Integrations → Deployment targets and choose Add deployment target (Add target once you have one).
3. Pick the Repository this target deploys. The target inherits the repository's tracking branch; you don't type a branch.
4. Pick the Platform and fill in the platform's fields (see the Vercel and Coolify sections below).
5. Press Create. DevSpec names the target after the repository and branch, for example web (main). You can rename it later by editing the target.

A setup panel then walks you through three steps:

1. Set it up on Vercel (or Coolify). DevSpec shows the webhook URL, with Setup instructions for your platform.
2. Paste the signing secret (Vercel) or Copy the webhook credentials (Coolify).
3. First delivery. Choose Yes, verify and DevSpec waits for a real deploy to arrive. Push an empty commit to the tracking branch (the panel gives you the command), or redeploy from your platform, and the panel confirms DevSpec is receiving your deployments.

You can leave with Set up later or Skip for now and finish later with Set up / verify webhook on the target's row. Use Edit target on the row to change its token, secret or name. The Setup Guide for a new project also offers Connect hosted deployment as an optional step.

Each repository also has a Delivery signal on its card in Project settings → Repositories, which tells DevSpec how that repository ships. Only Hosted deployment is tracked automatically; the other choices record how you ship, so setup doesn't ask you for a deployment platform you don't use.

Set up Vercel

Vercel webhooks need a Vercel Pro or Enterprise plan. Hobby accounts can't create them.

1. Create the target in DevSpec with Platform set to Vercel, and copy the webhook URL from the setup panel.
2. In Vercel, choose the team that owns the project and open Settings → Webhooks. Create a webhook, paste the DevSpec URL, and limit it to the project this target deploys.
3. Select these deployment events: Deployment Succeeded, Deployment Error, Deployment Created and Deployment Canceled.
4. Create the webhook, copy the signing secret Vercel shows you, and paste it into the setup panel's Webhook signing secret field. DevSpec stores it encrypted and never shows it again.

DevSpec rejects webhook deliveries until you save the signing secret in step 4, so every accepted delivery is verified as coming from Vercel.

API token (optional). Add a Vercel API token, when you create the target or later with Edit target, if you want DevSpec to read build logs and diagnose failures. Without one, failures are recorded but not analyzed. To create a token in Vercel: click your avatar, open the settings cog, go to Tokens → Create token, choose the account or team scope and an expiry, and copy the token (it starts with vcp_ and is shown once).

Vercel project ID (optional). Needed only to import past deploys. Find it in Vercel under the project's Settings → General → Project ID.

A canceled Vercel deploy is recorded as failed.

Set up Coolify

Coolify sends one webhook for every app in a Coolify team, so all your Coolify targets in a project share one URL, and DevSpec matches each notification to the right target by the app. Add one target per Coolify app you want to track; notifications for apps you haven't added are ignored.

1. Create the target with Platform set to Coolify. For Coolify application, paste the app's UUID: open the app in Coolify and copy the last part of its address (…/application/<uuid>), not its public domain. If you add a read token and the Instance base URL first, Load apps lets you pick the app by name instead.
2. In the setup panel's second step, copy the complete webhook URL. It already contains a secret DevSpec generated for you, and it's shown only once.
3. In Coolify, go to Settings → Notifications → Webhook for the team, turn it on, paste the URL exactly as shown, and enable Deployment Success and Deployment Failure.

To rotate the secret, edit the target and choose Generate new webhook secret (or Regenerate webhook secret). You get a new URL to paste into Coolify, and the old one stops working immediately.

How much of Coolify to connect

A Coolify token can read everything in the team it was created in. If you add one, consider putting the app in a dedicated Coolify team and creating the token there, so that's all DevSpec could ever see, and give the token an expiry.

Connect Coolify behind Cloudflare Access

If Cloudflare Access sits in front of your Coolify server, DevSpec's calls to the Coolify API are stopped by Access before they reach Coolify. Give the target an Access service token:

1. In Cloudflare Zero Trust, go to Access → Service Auth → Service Tokens and create one.
2. Add a Service Auth policy that allows the token on the Access application covering your Coolify API path (for example coolify.example.com/api/*).
3. Edit the target in DevSpec, open Behind Cloudflare Access?, and paste the Access client ID and Access client secret. DevSpec stores them encrypted.

The webhook itself doesn't need this: Coolify sends it to DevSpec, not the other way round. If DevSpec reports "Cloudflare Access refused the request before it reached the provider", the service token is missing, wrong or not allowed on that application. The Coolify token isn't the problem.

Import past deploys

Webhooks only tell DevSpec about deploys that happen after you connect. To bring in history, a target needs an API token plus, for Vercel, the Vercel project ID, or for Coolify, the Instance base URL and the app.

When a target has those, DevSpec imports its history automatically when you create or edit it. You can also run it yourself: on Project settings → Integrations → Deployment targets, choose Import past deployments (the history icon) on the target's row.

An import brings in the latest 50 deploys with their real deploy times, links them to tasks the same way live deploys are linked, and skips anything DevSpec already has, so it's safe to run again. Deploys with no commit are skipped. Imported deploys never send notifications or change an item's status; they only fill in the record.

How a deploy is linked to tasks

DevSpec links a deploy to a task when:

• the deployed commit is tagged with the item, as [devspec:<id>] in the commit message (agents do this for you);
• the deploy came from a branch named for the item, as agents' work branches are; or
• the commit is already linked to an item, for example because an agent recorded it or DevSpec auto-tracked it.

When you deploy a merge, DevSpec also looks at the commits the merge brought in since the last successful deploy to that target, and links every item they belong to.

A deploy that matches nothing is still listed on the Delivery page, without an item. See Commit tracking for how untagged commits become items.

What happens when a deploy succeeds

For each task a successful deploy shipped, DevSpec records the deploy on the item (in its Linked activity) and marks the work as live, so whoever checks it can see it has shipped. A Deployment failed mark from an earlier deploy clears.

If the item's agent never recorded its work, the deploy moves the item to Implemented for it, as long as no agent is still working on it.

DevSpec also notifies the item's assignees, or its creator when nobody is assigned, that the item "is live" and is "Ready to verify". This notification is off until each person turns on Deployments → Successes in Settings → Notifications. See How an item reaches Done for what happens next.

What happens when a deploy fails

Every failed deploy appears on the Delivery page as Failed.

If the target has an API token that can read build logs, DevSpec reads the log and shows the category of failure and a short summary under AI analysis. Without a token, the deploy shows "Build logs unavailable". If the token has expired or been revoked, edit the target to replace it.

If you have enabled an automation with the failed-deploy trigger, the failure starts an investigation on an eligible connected agent (preferring the agent that pushed the change when available) with the commit, deployment link and available logs. A later successful deploy cancels waiting investigations and lets any agent already investigating know that the target has recovered.

DevSpec itself never redeploys or retries a deploy on your platform. The automation's agent does the investigation and any permitted repair, or you can hand the failure to your agent yourself with Fix build.

When no automation starts and a failed deploy is linked to a task, DevSpec marks the item Deployment failed and notifies its assignees (or its creator).

Find the failed-deploy automation

Expand a failed deploy to see Investigate with an automation. If a visible automation is configured for that target, Delivery shows whether it is enabled and links to it. Recorded runs have a View investigation link that opens their history. If no automation is shown, Explore this automation takes you to Automations and introduces the included starter. You can customize it or create your own; following the link does not install, enable or run anything.

New installations of Investigate failed deploys allow the agent to commit and push a checked repair through the project's safe delivery workflow. Existing automation permissions do not change. Recovered failures show this guidance under For future failed deploys instead of offering a current repair.

Hand a failed build to your agent

On the Delivery page, click the failed deploy to open it.

• If it's linked to a task, open the item's Agent command (the terminal icon) in the deploy's details. Fix build is selected for you. Choose Send to an agent to deliver it to one of your connected agents in a session, or copy it under Or copy a command and paste it into your agent yourself.
• If it isn't linked, the details show Failed build with Copy fix-build prompt.

Either way the prompt carries the branch, the commit and the deployment ID, and asks your agent to pull the latest code, get the build log for that deploy, fix the error and push the change. Your agent does the work; DevSpec doesn't change your code. See Working with your agents.

Who is notified about deploys

Each person can change how they receive these in Settings → Notifications under Deployments (Failures and Successes). See Notifications and messages.

When a target isn't receiving deploys

The Delivery page and the setup panel watch what arrives and tell you what's wrong:

• Webhook signature is failing. Deliveries are arriving but were rejected because the signature didn't match: the secret saved in DevSpec differs from your platform's signing secret. Edit the target and paste the current secret.
• Deploys are arriving for a branch you don't track. Your platform is deploying a different branch from the target's. Choose Track branch instead to switch the target to that branch, or change what your platform deploys.
• Delivery arrived, but the payload couldn't be read. Check that the webhook is set up for deployment events and points at the target's URL.
• Nothing arrives at all. Use Test webhook on the Delivery page's checklist, then trigger a deploy and use Verify connection. Check that the URL on your platform matches the one on the target's row (Copy webhook URL), and that the right events are selected.

What delivery tracking costs, and how long deploys are kept

DevSpec keeps deploys for 90 days, including imported ones, and then deletes them from the Delivery page and from each item's Linked activity.

Receiving webhooks, listing deploys, linking them to items, importing past deploys and starting your agent's investigation are free. An investigation does not wait for a funded server-side diagnosis; your agent uses its own provider access. The only charge is diagnosing a failed deploy, which happens only when the target has an API token that can read build logs. It's background work charged to your organization's balance, and appears on Settings → Billing → Transactions as Running your project. See Billing, usage and limits.