Support Forums

Provide a commit sha to the build hook


I’ve started using build hooks so that I can use custom logic in GitHub Actions to choose when to build and deploy a new version.

I was wondering if there was the possibility (or the plan to add it) to specify a commit SHA to the hook instead of a branch? This would help avoid race conditions where 2 commits are processed at close interval but Netlify picks up the wrong one as it just gets the HEAD of the branch.


Adding to this, I’d like to describe my dream workflow and you can see the feature requests that it requires.

I have a monorepo, I would like to use GitHub Actions to determine when to trigger a Netlify build. This includes a mix of which branch is pushed (on > push > branches in GH Actions syntax) to and which files have changed (on > push > paths in GH Actions syntax).

When I trigger a deploy, I’d like to specify the context and the commit it should deploy as. Currently I can only specify a branch. Moreover, this workflow requires to disable the production branch in Netlify (I’ve set it as none) but then my “actual production branch” build triggered by the hook becomes a branch deploy, which messes around with the subdomain.

Since branch deploy are limited to subdomains of the main domain, I cannot use this bag-full-of-tricks workflow unfortunately. In the first place, if you have www.company.com and app.company.com on Netlify you’re also stuck with dev and staging envs like dev.app.company.com and staging.app.company.com. I use multiple sites on the same repo with different production branches to get around this issue.

All in all, I’m aware this might be a more advanced setup which needs to be balanced with the ease of use people love Netlify for. And it falls in the hands of the Netlify team to choose their tradeoffs. But I thought it might be worth to detail the dream workflow I have, as input to the team.


  • more options in build hooks: commit, context
  • less constraints with branch deploy subdomains

Goal: more control over when builds happen to avoid unnecessary builds.

What’s my status quo for now? I still love Netlify and feel thankful for the time it saves me, and I over build my frontend and functions whenever another part of my monorepo or docs change.

Hope this helps. :slight_smile:

Thanks for the thoughtful suggestions, Thibaut! I’m not sure we intend customization at that level - we intend to handle things in a 1:1 mapping of “this commit caused this build” but as you say, it can be suboptimal in case you commit a lot, quickly. I think if you use regular notifications from your git provider rather than build hooks, we may actually do it by commit hash rather than “HEAD” as the incoming buildhooks do, though?

So, I wonder if you could instead adapt your workflow use our monorepo support (which does not map perfectly to all monorepo workflows) to let us “run” the logic for you as to when to build? That might give you somewhat finer grained control:


Thanks @fool. The Netlify monorepo support is a bit too “tight” if I understand correctly. Let say my app package depends on some nifty-component package. If the changes only occur in nifty-component, app should build again, but if I set the base directory to app it won’t. Is that right?

It would need to know about packages dependencies to be productive, the way yarn workspaces do it for example. Not sure if that’s easy to detect at your level but you could see how wsrun manages that to build packages by stages in a dependency aware fashion.

That being said, your link also included words about build.ignore which I did not know about. And this will already reduce the pointless builds by a lot :).

I maintain the previous message as input to the team, but we’ve improved the status quo already :tada:.

Thank you.

Oups, just realized there is a catch. The docs suggest the following ignore config:

  ignore = "git diff --quiet HEAD^ HEAD sub_dir/"

The issue is we don’t know which commit to compare HEAD with, HEAD^ works only if each commit is pushed and deployed by Netlify. It would be useful to have a Netlify provided environment variable giving the LAST_COMMIT_REF that was successfully deployed. Do you think that’s something you would be keen to add? I suspect this should be super useful for plugins.

While it is worth asking, and I have filed an enahancement request, I don’t expect changes like that to arrive quickly. I will however notify this thread if it happens!

Today, I think you could use our API to query the current deploy’s details:

(or list deploys: https://open-api.netlify.com/#operation/listSiteDeploys and iterate through them looking for the details you need)

And you can see commit_ref there…

1 Like

Thanks for the response and details on the API. Appreciate the transparency setting expectations towards new features :).

Just realized, another way around this is to handle the whole build in GitHub Actions and use the Netlify CLI to manually deploy pre-built files as per the docs.

yup, that is possible, but you lose branch deploys and deploy previews if you do that - your options from the CLI are:

  • production deploy (autopublished)
  • draft production deploy (not autopublished)

And you lose all the “report build status and other deploy details to GitHub” type notifications too.

But, as far as getting a site deployed, yes, that is not a wrong way to do it :wink:

1 Like

Thanks for pointing out the trade offs. Really useful!

Hi, @tibotiber. There is now an environment variable which contains SHA for the most recent successfully build commit. There is more information here:

Quoting that page:

  • CACHED_COMMIT_REF : Reference ID (also known as ‘SHA’ or ‘hash’) of the last commit that we built before the current build.

This environment variable is intended to be used with a build.ignore command (which is usually some variation of git diff).

If this new environment variable doesn’t meet your requirements for any reason, please let us know.

Getting an unprompted update a year later, I must say you folks really rock at tracking requests. My hat off!

On this particular addition, how does it manage “history” and branches. E.g. if I have PR (branch) builds enabled the last successful build might be something like 3 commits before HEAD. However the last successful production build might be 25 commits before HEAD. So let say I’m making a new production build, which one is CACHED_COMMIT_REF going to point to?

Thanks again @luke

1 Like

Hey @tibotiber,
I wanna say (though am not 100% sure) that this is per branch. Your new production build’s CACHED_COMMIT_REF will be the ref before HEAD for that branch. But the PR branch’s CACHED_COMMIT_REF will be different. Let us know if you have any other questions (or prove me wrong :slight_smile: )

1 Like

Thanks @jen, that seems like just the right design. I don’t have bandwidth to test this out at the moment unfortunately but I’ll report back when I get to it.