GitLab Azure Integration and Deployment Architecture

The convergence of GitLab's robust version control and CI/CD orchestration with Microsoft Azure's expansive cloud infrastructure provides a powerful ecosystem for modern software delivery. This integration spans several distinct modalities, ranging from the deployment of a full-scale GitLab Self-Managed instance on Azure Virtual Machines to the seamless push of static front-ends via Azure Static Web Apps and the automated provisioning of infrastructure using Azure CLI within GitLab CI/CD pipelines. For the technical professional, understanding these various pathways is critical to minimizing deployment friction and maximizing the scalability of the application lifecycle.

GitLab Self-Managed Deployment on Azure Virtual Machines

For organizations requiring full control over their instance, GitLab offers a pre-configured offering within the Azure Marketplace. This approach streamlines the installation of GitLab Enterprise Edition by utilizing a pre-baked image, eliminating the need for manual package installation and complex initial configuration of the GitLab application stack.

Prerequisites and Account Tiers

Before initiating the deployment of a self-managed GitLab instance, an active Azure account is mandatory. The availability of this deployment depends on the subscription type:

• Existing subscriptions: Users or companies with established Azure subscriptions can utilize their current accounts.
• Free accounts: New users can create a free account, which provides a $200 credit for 30 days to explore the platform.
• MSDN subscriptions: Subscribers with MSDN benefits can activate their recurring monthly Azure credits.

The deployment is available across multiple GitLab tiers, including Free, Premium, and Ultimate, ensuring that the infrastructure can scale based on the organizational need for advanced features.

The Deployment Process

The deployment of GitLab on Azure is handled primarily through the Azure Portal via the Marketplace. Users can choose between two primary paths: creating a VM from scratch or utilizing a pre-set configuration to accelerate the setup process.

Once the VM creation is triggered, the process takes several minutes to complete. Upon completion, the VM and its associated resources are visible on the Azure Dashboard. A critical step during this phase is the management of the SSH key. The key must be downloaded during the process, as it is the sole mechanism required to securely SSH into the VM for administrative tasks.

Post-Deployment DNS and Domain Configuration

Once the VM is operational and the GitLab instance is deployed, the system is accessible via a public IP address, which is static by default. However, for production environments, relying on a raw IP address is insufficient.

Azure provides the ability to assign a descriptive DNS name to the VM. This is managed through the VM dashboard by selecting the Configure option under the DNS name section. For instance, entering a label such as gitlab-prod results in a fully qualified domain name (FQDN) such as gitlab-prod.eastus.cloudapp.azure.com. This ensures that the instance is accessible via a human-readable URL. While the Azure-provided DNS is a functional starting point, most professional deployments will eventually transition to a custom domain name for branding and ownership purposes.

Azure Static Web Apps Integration with GitLab

Azure Static Web Apps provides a globally distributed hosting service for static sites, and it features deep integration with GitLab. This workflow is specifically designed for developers who want to decouple their front-end hosting from their back-end logic while maintaining a unified CI/CD pipeline.

Repository Preparation and Import

The integration begins with the establishment of a source repository in GitLab. For those transitioning from other platforms, GitLab allows for the import of repositories via URL.

1. Navigate to the project creation page at https://gitlab.com/projects/new#import_project.
2. Select the Repo by URL option.
3. Provide the Git repository URL of the chosen framework.
4. Assign a project slug, such as my-first-static-web-app.

This process ensures that the source code is centralized in GitLab before the Azure connection is established.

Provisioning the Static Web App

Once the repository is live, the resource must be created within the Azure portal:

1. Select Create a Resource and search for Static Web Apps.
2. In the Basics section, configure the subscription and resource group.
3. For the Resource Group, a new group named static-web-apps-gitlab can be created.
4. Set the name of the app, such as my-first-static-web-app.
5. Select the Free plan type.
6. Crucially, the Source must be set to Other to allow for the GitLab integration.

Pipeline Configuration via .gitlab-ci.yml

The bridge between GitLab and Azure Static Web Apps is the .gitlab-ci.yml file. This file must use the .yml extension and utilize a specific Docker image provided by Microsoft for the deployment process.

The required configuration follows this structure:

```yaml
variables:
APITOKEN: $DEPLOYMENTTOKEN
APPPATH: '$CIPROJECT_DIR/src'

deploy:
stage: deploy
image: registry.gitlab.com/static-web-apps/azure-static-web-apps-deploy
script:
- echo "App deployed successfully."
```

The deployment relies on specific configuration properties to map the project structure correctly:

The $CI_PROJECT_DIR variable is a built-in GitLab CI/CD variable that maps to the root folder location of the repository during the build process.

Automated Azure Infrastructure Deployment via GitLab CI/CD

For more complex workloads, such as deploying Linux web apps or managing entire cloud environments, GitLab CI/CD can be used as an orchestration engine for the Azure CLI. This allows for Infrastructure as Code (IaC) patterns where resources are created and configured dynamically.

Authentication and Service Principals

To allow GitLab to interact with Azure, a Service Principal (App Registration) must be generated. This is achieved using the Azure CLI, and the user must possess the Owner role to assign the necessary scopes.

The command to generate the Service Principal is:

bash az ad sp create-for-rbac --name GitLabServicePrincipalName --role Owner --scopes /

This command outputs a JSON object containing the appId, displayName, password, and tenant. To maintain security, these values must not be hardcoded into the .gitlab-ci.yml file. Instead, they should be stored in GitLab under Settings > CI/CD > Variables. It is mandatory to enable the Mask variable checkbox for each secret to prevent sensitive credentials from appearing in the job logs.

Implementing the Deployment Pipeline

The pipeline utilizes the official Microsoft Docker image containing the Azure CLI. Because variables defined in the GitLab GUI are not automatically available as environment variables in certain contexts, they must be explicitly assigned within the variables block of the YAML configuration.

An example of a robust deployment job is as follows:

yaml deploy-job: image: mcr.microsoft.com/azure-cli variables: appId: $appId password: $password tenant: $tenant subId: $subId stage: deploy script: - az login --service-principal -u $appId -p $password -t $tenant - az account set -s $subId - az group list

Advanced Container Deployment Patterns

For those deploying Docker containers to Azure App Service, a more dynamic approach involving bash scripts and the Azure CLI is often employed. This allows for the dynamic naming of resource groups based on project metadata.

The process typically involves the following logic:

1. Define the resource group and app service names using GitLab predefined variables:
   RESOURCE_GROUP_NAME=$CI_PROJECT_NAME-$CI_ENVIRONMENT_SLUG
APPSERVICE_NAME=$RESOURCE_GROUP_NAME
2. Execute Azure CLI commands to create the infrastructure:
   bash az group create --name $RESOURCE_GROUP_NAME az webapp create --name $APPSERVICE_NAME az webapp config container set ...
3. Use deployment tokens with read access to the registry. These credentials are provided via the CI_DEPLOY_USER and CI_DEPLOY_PASSWORD variables.

In high-performance scenarios, such as deployments in specific regions like Australia East, organizations may choose to augment their GitLab container registry with an Azure Container Registry (ACR) to ensure that images are geographically closer to the deployment sites, thereby reducing latency and improving deployment speed.

Comprehensive Resource Mapping for Azure-GitLab Workflows

The integration of these two platforms can be summarized by the specific toolsets used for different deployment goals.

Conclusion

The deployment of GitLab to Azure, and the subsequent use of GitLab to deploy to Azure, represents a versatile architectural choice. Whether an organization opts for the streamlined path of the Azure Marketplace for a self-managed instance, the specialized workflow of Static Web Apps, or the highly customizable nature of Azure CLI-driven pipelines, the core requirement remains the same: secure authentication and precise configuration mapping. The use of Service Principals and masked variables ensures a secure handshake between the CI/CD runner and the Azure Resource Manager. Furthermore, the ability to leverage specific Docker images for deployment and the strategic use of Azure Container Registry for regional optimization allows for a professional-grade DevOps lifecycle that minimizes downtime and maximizes deployment velocity.

Sources

1. Install GitLab on Microsoft Azure
2. Azure Static Web Apps with GitLab
3. Deploy to Azure with GitLab Authentication
4. GitLab into Azure Video Series
5. GitLab Forum: Deploying to Azure from GitLab CI/CD