One of our customers at Thinktecture recently wanted to set up an auto deployment of its GitLab repository to an App Service hosted by Microsoft Azure. If you want to set up auto deployments for GitLab, you might be disappointed because this service is not included in the list of available services. Setting up auto deploy from GitLab.com or on-premises editions of GitLab is a manual process—luckily, it’s an easy one.
GitLab.com is a very popular service, as it allows free private Git repositories with up to ten gigabytes in size. If this still doesn’t suit your needs or you want to host the software yourself, GitLab also offers on-premises editions (Community Edition, free and Enterprise Edition, paid per user and year).
Microsoft Azure is a popular cloud service, offering so-called App Services (free plans available). App Services are used for hosting web apps or back-ends based on .NET, Node.js, Java, PHP and other technologies. An App Service can be set up to auto deploy changes that are pushed to a certain branch of a Git repository.
Here’s how to do it for GitLab.com or on-premises editions of GitLab:
Project Kudu
Project Kudu is the engine behind Git deployments in Microsoft Azure. Kudu is open-source and can also be used outside from Azure. The engine is in charge of pulling a given branch of a Git repository and then rolling it out using Web Jobs.
When you are creating a new App Service, a new instance of Project Kudu is automatically created as well, run under https://mysite.scm.azurewebsites.net, where mysite is the name of your App Service. Project Kudu uses basic authentication to protect itself from unauthorized access. The credentials can be found in the Azure portal.
Adding the Deploy Key to GitLab
Deploy keys grant read-only access to a GitLib repository. In order to grant Project Kudu access to your repository, you have to add the public key of your Kudu instance to GitLab’s list of allowed deploy keys. To retrieve the public key, you have to open Kudu by clicking Tools > Kudu > Go in your App Service’s blade in the Azure portal:
This automatically authorizes you to use Kudu. Now, replace the URL in the address bar to be https://mysite.scm.azurewebsites.net/api/sshkey?ensurePublicKey=1, where mysite is the name of your App Service. You should now see an output of "ssh-rsa <long random string here>". Please copy this entire value without the quotation marks.
Now switch over to the settings page of your GitLab project. Click the Deploy Keys menu entry in the navigation bar and then click the green New deploy key button. On this screen, add a description for the deploy key you are going to add (e.g. Azure Deployment) and paste the public key of your Kudu instance.
After clicking the Create Deploy Key button, switch back to the project by clicking the Go to Project link in the navigation bar and copy the SSH URL to the repository. Then go back to the Azure portal, where we will now add this Git repository for deployments.
Adding the Git Repository to Azure
In the Azure portal, click Settings on your App Service’s blade and then select the Deployment source menu entry in the Publishing group. Choose External repository as the source and paste the SSH URL of the repository in the Repository URL field.
It is recommended to use the master branch for deployments. It’s a common pattern that the master branch contains a deployable state of your web app or back-end at any point of time. To ensure that, GitLab provides a feature called protected branches to restrict access to the master branch. For instance, you could install a compulsory review before allowing to merge changes into the master branch in your workflow.
By the way, you can even add performance tests here which would be executed after every deployment.
After saving the changes, the first pull is performed. If the deploy key was added and the repository URL entered correctly, this should work immediately.
Triggering Redeployments via Webhook
After adding the Git repository to your App Service, Project Kudu is now able to pull the state from GitLab.com or the on-premises edition of GitLab. However, you would have to trigger the deployment manually, as Project Kudu does not get notified if a push to the repository happens. In order to achieve this, we are going to use Webhooks.
Next, we need to find out the user name and password for the Basic authentication of Project Kudu. Download the publish profile by clicking Get Publish Profile and extract the credentials from there using a text editor. A redeployment can be triggered by calling the https://$[mysite]:[password]@[mysite].scm.azurewebsites.net/deploy endpoint of Kudu, where [mysite] is the name of your App Service and [password] is the long random password found in the field above. Copy the information from this field to concat the URL in the form noted above.
Note: In case you want to target a specific deployment slot, instead use a URL of the form https://$[mysite]__[slotName]:[password]@[mysite].scm.azurewebsites.net/deploy. Replace [slotName] by the name of your deployment slot (e.g. development/production).
Now switch back to your GitLab project, go to the project settings and then click the Webhooks menu entry in the navigation bar. Paste the URL for triggering the deployment here and adjust the triggers. The default selection Push events should be the most common choice. Enable SSL verification should be turned on (and it is by default).
After clicking Add Webhook, you can test this hook by clicking the Test Hook button at the bottom of the page. By doing this, the hook is executed. If you open the deployment source view in Azure again, you should immediately see that a new deployment was issued.
Note: This hook will notify Azure for each push, regardless of the selected branch. However, a deployment will only be triggered if the selected branch changed.
Et voilà!
Your auto deployment from GitLab.com to Microsoft Azure is now set up. Depending on the technology that you intend do use, there might be some more required steps for your application to boot up. Now you’re app and running! Pun intended.
Thanks to Joshua Ellinger for pointing me at deployment slots and my colleague Christian Weyer for reviewing this blog post. The GitLab artwork is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
