The CI environment Pipeline usage

This section provides a guideline on how to use the CARML CI environment pipelines.

---

Navigation

• Operate the module pipelines
  • Add a new module pipeline
• Operate the dependencies pipeline
  • Add a new dependency
• DevOps-Tool-specific guidance
  • GitHub workflows
    • Trigger a workflow
    • Register a workflow
  • Azure DevOps pipelines
    • Trigger a pipeline
    • Register a pipeline

---

Operate the module pipelines

To validate updates to a module template, you can perform the following steps:

1. (Optionally) Update the module's parameter files to reflect your changes.
2. Push the local changes to the repository (using a branch that is not main|master).
3. On the DevOps platform, navigate to your pipelines and select the pipeline that was registered for the module you updated.
4. Select the branch with your updated template.
5. (Optionally) disable the Remove deployed module input parameter in case you don't want to apply the default behavior and want to skip the deletion of the test-deployed resources to check them post-deployment.
6. (Optionally) adjust the Publish prerelease module flag in case you want to publish a prerelease version of your updated module from your development branch.

   Note: The module version is assigned a prerelease suffix.

7. Trigger the pipeline.

Once the pipeline concludes, it will either be in a green (success) or red (failed) state, depending on how the module performed.

Pipeline logs are available for troubleshooting and provide detailed information in case of failures. If errors occur in the Static validation phase, you may only see the failed test and need to expand the error message. How this looks like depends on the DevOps platform you use.

Add a new module pipeline

To add a new module pipeline, we recommend to create a copy of a currently existing module pipeline and adjust all module-specific properties, e.g., triggers and module paths. The registration of the pipeline depends on the DevOps platform you're using.

Operate the dependencies pipeline

The dependencies pipeline must be triggered manually. This deploys a set of resources we reference as part of the module tests (e.g., Virtual Networks, Log Analytics Workspace, Key Vaults).

To run the dependencies pipeline you can perform the following steps:

1. Before running the pipeline for the first time make sure to update the following values:

   File	Parameter	Description
   utilities\pipelines\.. ..dependencies\Microsoft.KeyVault\.. ..vaults\parameters\parameters.json	accessPolicies.value[0].objectId	The 'Backup Management Service' needs access to back up the keys and secrets, along with the associated VMs. The Enterprise Application's object ID is unique per tenant.

2. (Optionally) Verify if you are satisfied with the dependency resource names by checking dependency parameter files stored in path utilities\pipelines\dependencies. If not, make the necessary updates to you local branch and push the local changes to the repository.

   Note: If you want to rename any dependency resources, make sure to update any references to their name in the module parameter files too.

3. On the DevOps platform, navigate to the dependencies pipeline.

4. Select the branch you intend to run.

5. (Optionally) Enable the 'Enable SqlMI dependency deployment' switch to include the deployment of the dependencies for the [SQL managed instance] module.

6. (Optionally) Enable the 'Enable deployment of a vhd stored in a blob container' switch to include the deployment of the dependencies for the [Compute Images] and [Compute Disks] modules.

   Note: This option requires up to two hours to complete.

7. Trigger the pipeline.

By default, i.e., by keeping the optional flags disables, the dependencies pipeline may take up to 30 minutes to run.

Note: For details about the dependencies pipeline design, please refer to the dedicated Dependencies pipeline design section.

Add a new dependency

Depending on what you want to test in your module pipeline, you may want to include additional resources to your dependencies pipeline. If so, make sure to include an additional parameter file for each service you require under utilities/pipelines/dependencies. Once done, you need to add the deployment to the pipeline itself making sure to deploy the new resources in the correct order. The implementation depends on the DevOps platform you're using.

---

DevOps-Tool-specific guidance

This section provides a step-by-step guideline on how to operate the pipelines based on the chosen DevOps platform, GitHub or Azure DevOps.

GitHub workflows

This section focuses on GitHub Actions & Workflows.

GitHub workflows

Trigger a workflow

To trigger a workflow in GitHub:

1. Navigate to the 'Actions' tab in your repository.

   

2. Select the pipeline of your choice from the list on the left, followed by 'Run workflow' to the right. You can then select the branch of your choice and trigger the pipeline by clicking on the green 'Run workflow' button.

   

Note: Depending on the pipeline you selected you may have additional input parameters you can provide aside from the branch. An outline can be found in the Module pipeline inputs section.

Register a workflow

To register a workflow in GitHub you have to create the workflow file (.yml) and store it inside the .github/workflows folder.

Note: Once merged to main|master, GitHub will automatically list the new workflow in the 'Actions' tab. Workflows are not registered from a branch unless you specify a temporal push trigger targeting your branch.

Azure DevOps pipelines

This section focuses on Azure DevOps pipelines.

Azure DevOps pipelines

Trigger a pipeline

To trigger a pipeline in Azure DevOps:

1. Navigate to the 'Pipelines' section (blue rocket) and select the pipeline you want to trigger.

   

2. Once selected, click on the 'Run pipeline' button on the top right.

   

3. Now you can trigger the pipeline by selecting the 'Run' button on the bottom right.

   

Note: Depending on the pipeline you selected you may have additional input parameters you can provide aside from the branch. An outline can be found in the Module pipeline inputs section.

Register a pipeline

To register a pipeline in Azure DevOps:

1. Create a workflow file (.yml) and upload it to a repository of your choice (e.g., in Azure DevOps or GitHub).

2. Navigate to the 'Pipelines' section (blue rocket) and select the 'New pipeline' button on the top right.

   

3. Next, select the repository-type you stored your template in. Azure DevOps will then try to fetch all repositories you have access to.

   

4. Now, we have to select the particular repository to get the pipeline file from.

   

5. Following, choose 'Existing Azure Pipelines YAML file' on the bottom of the list.

   

6. The previous action will open a new blade that asks you for the branch you stored the pipeline file in (e.g., master) and then asks for the relative path (from root of the repository) of the pipeline file.

   

7. Finally, Azure DevOps should show you the pipeline file you created. The last thing you have to do is to either select 'Run' on the top right (which will save & run the pipeline), or click the little arrow next to it and just save the pipeline.

8. Once saved you can also re-name / move the pipeline in the same view. However, this only works once you saved the pipeline at least once.