Switching Netlify built-in repos to Azure DevOps

I recently got into a sticky situation where I needed to move code from a repository hosted on BitBucket into one hosted on Azure DevOps, but this particular repo was backing a Netlify site that had autodeployments configured. I quickly found via Googling that I could indeed set up Netlify to use Azure (though it was trickier), but what I couldn’t figure out was how to switch it from BB to Azure. You can’t do it via the web, and so at first I resorted to creating a whole new Netlify site backed by the new repo, before figuring out this easier way to do it.

Through experimentation and thanks to the instructions in that previous link, this guide should help you move an existing Netlify site from the built-in supported repos to Azure DevOps.

(This guide assumes you have the Netlify CLI installed and logged in as the appropriate user.)

Step 1: Removing the old repository link

To remove the already existing GitHub/BitBucket/GitLab repository link, you need to run an API command. The easiest way to do this is from the command line.

1. If you haven’t already, use netlify init in your local code’s directory to establish the link between that directory and the Netlify site config
2. Find your site’s ID by going to the Netlify dashboard for the site, then Site Settings > General > Site Details > API ID. Copy this.
3. Using the Netlify CLI, run netlify api unlinkSiteRepo --data '{"site_id":"[YOUR SITE ID]"}'. This will remove the site repository link and details that you cannot remove from the web UI. You can go to the site settings for Deploys and note that the previous link to the repository is gone.

Step 2: Preparing the local repo to be relinked

Now that you have removed the otherwise stubborn old repository link, you are almost ready to hook up your new repo with Netlify. But first, you have to verify a couple of settings that could get you stuck and back at Step 1 if we don’t address them right now. Specifically, Netlify needs to know the Git SSH address to target so that it can clone the code from the repo, and the easiest way is to get that set up now.

When cloning a repo from most places (and by default when cloning from ADO), you’ll typically clone it via HTTP. However, in this case, let’s set it up to clone via SSH instead. In the Azure DevOps root page of your repository, click the “Clone” button in the top left. Next to the address for the repo, switch from the HTTPS toggle to SSH, and you should see the address change. Copy that address. At this point you may also need to set up Azure to recognize your machine’s public SSH key, adding it in via the “Manage SSH Keys” link just below the address box.

Note: it may be that you can leave your repository using HTTPS for the remote address by changing the repository address during the netlify init process, but I wasn’t getting lucky there so I did it this foolproof way.

1. With the SSH clone address in hand, and assuming you’ve previously cloned the repo locally, we need to change the remote’s address. Go to your local code repo in the terminal.
2. Assuming your Azure remote is configured as origin (very likely is), execute git remote remove origin
3. Now add the origin back in by using git remote add origin [SSH ADDRESS HERE]
4. Test your connection to the remote’s address by running a git fetch. It should be using your SSH keys to get in. If all is well and you can fetch/pull, go to the next step.

Step 3: Tell Netlify about the new repo config

With our local repo configured with the Azure SSH Git address, we can finally tell Netlify to use our new config. This involves re-initializing the repository link, but don’t worry, you shouldn’t lose any other configuration settings with your site; just the repo links.

1. Run netlify init from the code folder
2. Start stepping through the prompts, noting that you are setting up a manual repository link.
3. During the init process, Netlify will give you an SSH key that you’ll need to add to Azure DevOps so that Netlify can pull your repository’s code. Copy that and add it in to Azure via the same means as adding your own key. (Easiest way is to click that “Manage SSH Keys” link and add it on the linked page.)
4. Also during the init process, it will give you a web hook address. But according to one of the Netlify devs, you should ignore this one because it’s broken for some reason?
5. With the init process complete, go to the Web UI for the Build and Deploy settings section, and you should see your Azure repo address in there, woohoo! Almost done.
6. Go to the Build Hooks section of Build and Deploy, and click “Add build hook”. It will give you a URL, which you copy.
7. Go back to Azure, go to Project Settings > Service Hooks > add a new service hook. I set my service hook to use the “Code pushed” event, tied specifically to the target repository on the master branch only. Click Next, and in the appropriate box, paste in the Netlify Webhook URL and save.

Whew! At this point you should actually have all the pieces in place. Try it out by making a small change to your site and pushing to Azure, and hopefully see the build get triggered. Behind the scenes, as code is pushed to the master branch Azure is pinging Netlify via the webhook to simply say “Hey code was pushed!” The Netlify uses its SSH key that it gave you previously to check the most recent code out from master via SSH on your repo, and builds that. Pretty basic connections behind the scenes, but a bit difficult to set up.

But now you’re good to go with an Azure DevOps repo as your backing instance for your Netlify site. Congrats!