Last reviewed by Netlify Support Staff: December 2024
It is easiest to link a repository in Netlify’s UI; doing it via API is challenging and should be a rare use case. Nonetheless, it is possible to create a Netlify site linked to a repository at any of our supported git providers programatically. Specifically, it is possible to use Netlify’s REST API for these situations. You’ll probably be interested in the general topics around “how do I use Netlify’s REST API?” (see this support guide, as well as our public documentation on the topic).
You can link a repository while you create a site. This is an example (partial) payload from such a successful site creation (sent via HTTP POST to https://api.netlify.com/api/v1/sites).
{
"repo": {
"branch": "main",
"cmd": "jekyll build",
"deploy_key_id": "5a908857a6188f466bed"
"dir": "_site/",
"private": false,
"provider": "github",
"repo": "account_name/repository_name",
"repo_id": 74777123
}
}
Note that there are two ID’s there - a GitHub repo ID (which you can get from their API) - and similar ID’s are needed for GitLab, BitBucket, and Azure DevOps - though, for bitbucket (at least), the ID will have the format login/project or workspaceName/project instead of being a literal ID number. The second ID is a deploy key ID . You’ll need to create the Deploy Key via our API before you’ll be able to create a usable repo object, so that is the call you have to make FIRST, before creating the site.
The call to create a deploy key is an HTTP POST to https://api.netlify.com/api/v1/deploy_keys . This call responds with JSON containing public_key and id parameters (you’ll need to put the public_key in place at your git provider. For most of the other providers this can be done on the repo level i.e adding it to repository settings but for Azure DevOps add this to user settings under SSH keys. Due to this limitation in Azure, a good approach is using a service account in case a user’s access is revoked), and keep the id value, for using with the repo definition I already quoted.
You’ll also need to change the value of provider based on what you use - “github”, “gitlab”, “bitbucket”, “azure_devops”, and “manual” are the options. manual is intended for anything other than repos hosted at any of github.com, gitlab.com, bitbucket.org, or dev.azure.com as of June 2020. In July 2020, we created the ability for Business & Enterprise customers to link their self-hosted (GitHub Enterprise/GitLab self-hosted) repos to our service directly, so please ping us in the helpdesk (all non-Starter users can email support@netlify.com directly from their Netlify login email address) if you’re at that account level and need API help setting up a self-hosted repo. Note that, as on August 2023, the Business plan has been deprecated, so the self-hosted repo feature should now be restricted to the Enterprise plan.
When you link a site through our UI, we programatically configure the settings required at your git provider to tell us about your commits and merges. When you instead do it yourself - you also need to configure that part yourself! You can either:
- create a webhook to https://api.netlify.com/hooks/github (or
gitlab, orbitbucket, orazure_devopsas that last path component). This webhook should be:- using content-type
application/json - POST on the events you want us to know about: likely commit, and potentially PR/merge/branch deletion events.
- using content-type
OR
- if and only if you are on GitHub: set up a sample site through our UI, linking with the GitHub app (this is the only way to link a GitHub repo through our UI for the past 2.5 years or so), find the “installation ID” of our GitHub App (it will be the final path component when you click “configure” on our installed app at https://github.com/ACCOUNTNAME/settings/applicationsor https://github.com/orgs/YOURORGNAME/settings/applications - it will be an integer), and include that in the repo object as quoted above, as a parameter like this:
"installation_id": "X",
Either of these workflows will tell the git provider to tell us about commits.
You can also use our CLI to link a repo, see this forum thread for more details.
If you have further questions, please start a new thread with your site name, a link to your repo, and the steps you have tried. Thanks!
What does “doesn’t work” look like in more detail, please? Happy to help you get things sorted, but you’ll want to follow our guide on asking good questions to help us understand what you are seeing: 
