Publish a build through Netlify API/CLI

Hey there.

Is there a way to publish a build (to production) using Netlify API/CLI ( ) ?

I know there’s a way to manually deploy something using Netlify CLI, but a scenario about which we’re asking is:

  • Netlify automatically makes a build after a commit appears on github
  • laater on, our through manual approval process on our CircleCI, we want to notify Netlify, that a build for that given git commit, should be published on production .

It’s a requirement of our client, as we have many different apps and services, and deployment of all of them to production is currently done by approval jobs on CircleCI, and we would like to avoid the need of manually clicking the stuff in Netlify Dashboard, if it could be done automatically with CI instead.

Hi @jtom, yes this is possible using our API using the deploy restore endpoint:

You can find our swagger spec for the Netlify API at

This also should be possible with the new netlify api CLI command once this PR lands

netlify api restoreSiteDeploy --data 'the payload'

I’ve put together a workflow for jekyll that uses a build hook to deploy when a circleci job passes.

I’m using it in conjunction with github peer reviews (i.e., the protected master branch requires a peer review on a given PR) to achieve a result analogous to what you’re describing. So our content creators create branches to their heart’s content, netlify builds preview sites, and circleci runs each commit through HTML proofer, etc. Then, when it is time to deploy, we just merge a passing build into master, and circleci deploys via a netlify Build Hook. Technically, the peer review isn’t even necessary, because it’s the merge and subsequent passing circleci operation that makes the magic happen. That’s our approval step, though – it’s just in github instead of via the CircleCI Job Approval paradigm.

Here’s a templated version of what we’re doing that I threw together. Hope this is helpful.

1 Like

wow, that is great to see, @fuery! Thanks so much for sharing!

@fuery thanks for your share! I saw in your jekyll-netlify-circleci repo that you hit the build hook at the end of the circleci job that occurs from merge commits onto master. From that, I assume you’ve set your production branch as not master since you only want to initiate deploys (and the subsequent auto-publishe, I also assume) from the circleCI build that happens after the content-branch is committed as a merge into master, and not automatically by Netlify. I’m curious about the following:

  1. Since all the builds already passed upon tests on the PR, why did you decide to not have Netlify auto-deploy and publish anyway, once they’re committed into master?

  2. So how did you go about enabling Netlify’s commit checks for the PR then (the header rules, mixed content checks etc.), since they don’t run for master anymore bc it’s not labelled in netlify as your production branch? Or are some of my assumptions wrong?

I’m mulling over these questions right now as I set up my CI/CD flow, and am considering a setup exactly like yours. Would love to hear your thoughts.

Hello @futuregerald , thanks for sharing this endpoint !
I have implemented it but it doesn’t seem to work on a project with autopublish desactivated.

I trigger the deploy / publish once I tag my master branch but I don’t want the autopublish on it, is there any trick to keep the autopublish locked and still be able to use the restore endpoint on my project ?
(I thought about unlocking the project before doing the restore then relocking it through api call but is it the only solution ? )

Thanks a lot

Toggling the auto-publish option from the API is one option. The other option would be to “flip” your mentality! You could keep auto-publish on and create logic to ignore/cancel certain builds. But, the former is perhaps the easiest. :+1:

1 Like

I also have a similar situation where we want to disable auto publishing and use GitHub actions to trigger a publish of the site. I have managed to get it to trigger a build using the api but I wondered if there was a nice way to watch a build to see when it has deployed successfully before making it live. This is the script I currently have:


DEPLOY_DATA=$(netlify api createSiteBuild --data "{ \"site_id\": \"$SITE_ID\" }")

DEPLOY_ID=$(echo $DEPLOY_DATA | jq '.deploy_id')

# Need a way here to check that build had finished and is successful before making it live.

netlify api restoreSiteDeploy --data "{ \"site_id\": \"$SITE_ID\", \"deploy_id\": $DEPLOY_ID }"

The netlify watch command waits for all build to finish so that isn’t something I want to use. Unless there is a way to watch a specific build?

I may end up resorting to polling the getSiteDeploy endpoint in the end to check the status of the build. Like this:

netlify api getSiteDeploy --data "{ \"site_id\": \"$SITE_ID\", \"deploy_id\": $DEPLOY_ID }"

Is there any nicer way to do this or am I just approaching it in the wrong way?