[Support Guide] Linking a repository via API

fool · September 15, 2020, 11:58pm

While it is easier to link a repository in Netlify’s UI than programatically, there are cases in which you don’t want to do that. Fortunately, 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?” and our public documentation on the topic.

You can link a repository while you create a site. This is an example payload from such a successful site creation (sent via HTTP POST to https://api.netlify.com/api/v1/sites).

{"repo":
  {"provider":"github",
   "id":74777123,
   "repo":"account_name/repository_name",
   "private":false,
   "branch":"master",
   "cmd":"jekyll build",
   "dir":"_site/",
   "deploy_key_id":"5a908857a6188f466bed"
   }
}

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 and BitBucket as well. 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 this is the call you have to make FIRST, before creating the site.

The call to achieve this 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), 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”, and “manual” are the options. manual is intended for anything other than repos hosted at any of github.com, gitlab.com, or bitbucket.org as of June 2020. In July we created the ability for Enterprise customers to link their self-hosted (GitHub Enterprise/GitLab self-hosted) repos to our service directly, so please ping us in the helpdesk if you’re at that account level and need API help setting up a self-hosted repo.

Finally, please be aware that you need to configure your git provider to build in this case. 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 do it yourself - you need to configure that yourself. You can either:

create a webhook to https://api.netlify.com/hooks/github (or gitlab, or bitbucket as 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.

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 1.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/orgs/YOURORGNAME/settings/applications - it will be an integer), and apply that to the repo object in the above data as a parameter:

"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.