|
| 1 | +--- |
| 2 | +hidden: true |
| 3 | +--- |
| 4 | + |
| 5 | +# Azure DevOps |
| 6 | + |
| 7 | +Before setting up the pipeline in Azure DevOps, make sure that the following steps from the [Configuring a CI/CD pipeline](./) are done: |
| 8 | + |
| 9 | +* Pick a Cloud project |
| 10 | +* Activate CI/CD Flow |
| 11 | + |
| 12 | +Next, you will need to define your pipeline in YAML and use it to interact with the Umbraco Cloud API. |
| 13 | + |
| 14 | +{% hint style="info" %} |
| 15 | +The Umbraco CI/CD Team has created a sample pipeline for Azure DevOps. |
| 16 | + |
| 17 | +The Scripts are provided as is. This means that the scripts will do the bare minimum for a pipeline that is utilizing the CI/CD flow.  |
| 18 | + |
| 19 | +You'll need to adapt and integrate the script into your own pipelines to gain the ability to do deployments to your Umbraco Cloud projects. |
| 20 | + |
| 21 | +The sample includes YAML-files and custom Powershell and Bash scripts to interact with the Umbraco Cloud API. |
| 22 | + |
| 23 | +You can get the samples for both `Azure DevOps` and `GitHub Actions` from the [GitHub repository](https://github.com/umbraco/Umbraco.Cloud.CICDFlow.Samples). |
| 24 | + |
| 25 | +Samples that target the endpoints described here are located in the V1 folder. |
| 26 | +{% endhint %} |
| 27 | + |
| 28 | +{% hint style="warning" %} |
| 29 | +Please be aware that since this involves using your custom pipeline, any issues that arise will need to be resolved by you. |
| 30 | +{% endhint %} |
| 31 | + |
| 32 | +## Import Cloud project repository to Azure DevOps |
| 33 | + |
| 34 | +Go to your repositories in Azure DevOps and click on "Create a repository". |
| 35 | + |
| 36 | +* Create a new empty repository (don't add a README and don't add a .gitignore), and note down the clone URL. |
| 37 | +* Go to the Umbraco Cloud Portal and clone your cloud project down locally. [This article](../../../working-locally.md#cloning-an-umbraco-cloud-project) describes how you can find the clone URL. |
| 38 | +* Now working locally remove the Git Remote called `origin`, which currently points to Umbraco Cloud |
| 39 | + |
| 40 | +```sh |
| 41 | +git remote remove origin |
| 42 | +``` |
| 43 | + |
| 44 | +* Optionally rename branch `master` to `main` |
| 45 | + |
| 46 | +```sh |
| 47 | +# optional step |
| 48 | +git branch -m main |
| 49 | +git symbolic-ref HEAD refs/heads/main |
| 50 | +``` |
| 51 | + |
| 52 | +* Add a new remote called origin and pointing to the Azure DevOps clone URL and push |
| 53 | + |
| 54 | +```sh |
| 55 | +git remote add origin https://{your-organization}@dev.azure.com/{your-organization}/{azure-project-scope}/_git/{your-repository} |
| 56 | +git push -u origin --all |
| 57 | +``` |
| 58 | + |
| 59 | +Now we can move on to setting up a pipeline. |
| 60 | + |
| 61 | +## Set up the Azure DevOps pipeline files |
| 62 | + |
| 63 | +While working with the project on your local machine, follow these steps to prepare the pipeline, using the [samples from the repository](https://github.com/umbraco/Umbraco.Cloud.CICDFlow.Samples). |
| 64 | + |
| 65 | +{% hint style="info" %} |
| 66 | +Download the provided sample scripts as ZIP from the [GitHub repository](https://github.com/umbraco/Umbraco.Cloud.CICDFlow.Samples/). Click on "Code" and then choose "Download ZIP". Then unzip it and use the appropriate files from the V2 folder for the next steps. |
| 67 | +{% endhint %} |
| 68 | + |
| 69 | +Select your preferred scripting language: |
| 70 | + |
| 71 | +{% tabs %} |
| 72 | +{% tab title="Powershell" %} |
| 73 | +For a pipeline that uses Powershell scripts you will need the following files: |
| 74 | + |
| 75 | +* From the root folder |
| 76 | + * `cloud.zipignore` |
| 77 | +* From the `powershell` folder |
| 78 | + * `Get-LatestDeployment.ps1` |
| 79 | + * `Get-ChangesById.ps1` |
| 80 | + * `Apply-Patch.ps1` |
| 81 | + * `New-Deployment.ps1` |
| 82 | + * `Add-DeploymentPackage.ps1` |
| 83 | + * `Start-Deployment.ps1` |
| 84 | + * `Test-DeploymentStatus.ps1` |
| 85 | +* From the `powershell/azuredevops` folder |
| 86 | + * `azure-release-pipeline.yml` |
| 87 | + * `cloud-sync.yml` |
| 88 | + * `cloud-deployment.yml` |
| 89 | + |
| 90 | +**Do the following to prepare the pipeline:** |
| 91 | + |
| 92 | +* Copy the `cloud.zipignore` file to the root of your repository |
| 93 | +* Make a copy of the `.gitignore` from your repository and call the copy `cloud.gitignore` |
| 94 | + * Both files should be in the root of your repository |
| 95 | + * In the bottom of the `.gitignore` file add the line `**/git-patch.diff` |
| 96 | +* Also in the root, create a folder called `devops` |
| 97 | +* Copy the 3 YAML files from the `powershell/azuredevops` folder into the `devops` folder |
| 98 | +* Inside `devops` create an additional folder called `powershell` |
| 99 | +* Copy the Powershell scripts from the `powershell` folder to the `powershell` folder |
| 100 | +* **Note**: If you have not changed the branch to `main`, then in the `azure-release-pipeline.yaml` file change the branch from `main`to `master.` |
| 101 | +* Commit all changes, and push to Azure DevOps |
| 102 | +{% endtab %} |
| 103 | + |
| 104 | +{% tab title="Bash" %} |
| 105 | +For a pipeline that uses Bash scripts you will need the following files: |
| 106 | + |
| 107 | +* From the root folder |
| 108 | + * `cloud.zipignore` |
| 109 | +* From the `bash` folder |
| 110 | + * `get_latest_deployment.sh` |
| 111 | + * `get_changes_by_id.sh` |
| 112 | + * `apply-patch.sh` |
| 113 | + * `create_deployment.sh` |
| 114 | + * `upload_package.sh` |
| 115 | + * `start_deployment.sh` |
| 116 | + * `get_deployment_status.sh` |
| 117 | +* From the `bash/azuredevops` folder |
| 118 | + * `azure-release-pipeline.yml` |
| 119 | + * `cloud-sync.yml` |
| 120 | + * `cloud-deployment.yml` |
| 121 | + |
| 122 | +**Do the following to prepare the pipeline:** |
| 123 | + |
| 124 | +* Copy the `cloud.zipignore` file to the root of your repository |
| 125 | +* Make a copy of the `.gitignore` from your repository and call the copy `cloud.gitignore` |
| 126 | + * Both files should be in the root of your repository |
| 127 | + * In the bottom of the `.gitignore` file add the line `**/git-patch.diff` |
| 128 | +* Also in the root, create a folder called `devops` |
| 129 | +* Copy the 3 YAML files from the `bash/azuredevops` folder into the `devops` folder |
| 130 | +* Inside `devops` create an additional folder called `scripts` |
| 131 | +* Copy the Bash scripts from the `bash` folder to the `scripts` folder |
| 132 | +* **Note**: If you have not changed the branch to `main`, then in the `azure-release-pipeline.yaml` file change the branch from `main`to `master.` |
| 133 | +* Commit all changes, and push to Azure DevOps |
| 134 | +{% endtab %} |
| 135 | +{% endtabs %} |
| 136 | + |
| 137 | +## Configure Azure DevOps |
| 138 | + |
| 139 | +The pipeline needs to know which Umbraco Cloud project to deploy to. In order to do this you will need the `Project ID` and the `API Key`. [This article](./#obtaining-the-project-id-and-api-key) describes how to get those values. |
| 140 | + |
| 141 | +* Now go to the repository in Azure and click on "Set up build". |
| 142 | + |
| 143 | +<figure><img src="../../../../.gitbook/assets/azuresetupbuild.png" alt=""><figcaption><p>Azure DevOps Repository</p></figcaption></figure> |
| 144 | + |
| 145 | +* On the next screen click on "Existing Azure Pipelines YAML file" |
| 146 | + |
| 147 | +<figure><img src="../../../images/Pipeline3.png" alt=""><figcaption><p>Configure pipeline with existing YAML file</p></figcaption></figure> |
| 148 | + |
| 149 | +* Select `main` (or `master` if you did not change the branch name) in Branch |
| 150 | +* Select `/devops/azure-release-pipeline.yaml` in Path and continue |
| 151 | + |
| 152 | +<figure><img src="../../../images/Pipeline4.png" alt=""><figcaption><p>Select Branch and Path</p></figcaption></figure> |
| 153 | + |
| 154 | +* Now you are on the "Review your pipeline YAML" screen |
| 155 | + * Replace the `##Your project Id here##` with the Project Id you got from Umbraco Cloud Portal |
| 156 | + * Click on "Variables" |
| 157 | + |
| 158 | +<figure><img src="../../../../.gitbook/assets/azdevops-pipeline-variables.png" alt=""><figcaption><p>Pipeline variables in Azure DevOps</p></figcaption></figure> |
| 159 | + |
| 160 | +* Add the variable `umbracoCloudApiKey` with the value of the API Key you got from Umbraco Cloud Portal |
| 161 | + |
| 162 | +{% hint style="info" %} |
| 163 | +It is recommended to handle the `API Key` as a secret. This can be done by ticking the "Keep this value secret" checkbox. |
| 164 | + |
| 165 | +<img src="../../../../.gitbook/assets/azdevops-secret-variable.png" alt="Make the variable secret in Azure DevOps" data-size="original"> |
| 166 | +{% endhint %} |
| 167 | + |
| 168 | +{% hint style="info" %} |
| 169 | +You can customize the names for the variables as you like, however, you then need to rename the affected variables in `azure-release-pipeline.yaml`. |
| 170 | + |
| 171 | +Check the references to the variables in the yaml files match the variable syntaxes in the created variable. Example: `umbracoCloudApiKey` = `UMBRACOCLOUDAPIKEY`. |
| 172 | +{% endhint %} |
| 173 | + |
| 174 | +When you click on "Save and Run" your first deployment will be triggered. Which means that Azure DevOps is set up with all the needed information to be able to deploy your Cloud project back to Umbraco Cloud. |
| 175 | + |
| 176 | +### Optional: Test the pipeline |
| 177 | + |
| 178 | +With everything set up, you may want to confirm that Umbraco Cloud reflects the changes you are sending via your pipeline. |
| 179 | + |
| 180 | +While working on your project locally, add a new Document type. |
| 181 | + |
| 182 | +* Commit the change to `main` branch (or `master` if you did not change the branch name) and push to your repository. |
| 183 | +* The pipeline starts to run |
| 184 | +* Once the pipeline is done log into Backoffice on your left-most environment in Umbraco Cloud |
| 185 | +* Go to the Settings section and see that your new Document type has been deployed |
| 186 | + |
| 187 | +## High level overview of the pipeline components |
| 188 | + |
| 189 | +The mentioned scripts are provided as a starting point. It is recommended that you familiarize yourself with the scripts and with documentation related to how to use Azure DevOps. |
| 190 | + |
| 191 | +The scripts demonstrates the following: |
| 192 | + |
| 193 | +* How to sync your Azure DevOps repository with the [left-most project environment](../../../../deployment/) in Umbraco Cloud |
| 194 | +* How to deploy changes to the left-most project environment in Umbraco Cloud |
| 195 | + |
| 196 | +### Main |
| 197 | + |
| 198 | +The `azure-release-pipeline.yaml` is the main pipeline, and is the one that will be triggered on a push to `main` branch. You can configure a different trigger behavior in this file. |
| 199 | + |
| 200 | +You can add your Build and Test stage between the `cloudSyncStage` and `cloudDeploymentStage` stages. Keep in mind that you do not need to retain the dotnet build artifact for upload later. The `cloudDeploymentStage` job will take care of packaging all your source code and upload to Umbraco Cloud. |
| 201 | + |
| 202 | +### Cloud-sync |
| 203 | + |
| 204 | +The `cloud-sync.yml` shows how you can sync your Azure DevOps repository with the left-most environment of your Cloud project. In this sample, it accepts any change from the API and applies and commits it back to the branch which triggered the pipeline. However the commit does not trigger the pipeline again. |
| 205 | + |
| 206 | +If you don't want the pipeline to commit back to the triggering branch, this is where you need to change the pipeline. |
| 207 | + |
| 208 | +### Cloud-deployment |
| 209 | + |
| 210 | +The `cloud-deployment.yml` shows how you can deploy your repository to the left-most environment of your Cloud project. The sample shows how to prepare for deployment, request the deployment and wait for cloud to finish. |
| 211 | + |
| 212 | +There are a couple of things here to be aware of: |
| 213 | + |
| 214 | +* We are overwriting the `.gitignore` file with `cloud.gitignore`. This is a way to accommodate your gitignore-needs when working locally. For instance you might want to ignore frontend builds, but you want them build and published to cloud. |
| 215 | +* We have a special `cloud.zipignore` file. This is a convenient way to tell the pipeline which files **not** to include when creating the zip package to send to cloud. |
| 216 | + |
| 217 | +{% hint style="info" %} |
| 218 | +If you have frontend assets that needs to be built (using npm/yarn or other tools), add the needed steps before `Zip Source Code`. This ensures that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud. |
| 219 | +{% endhint %} |
| 220 | + |
| 221 | +## Further information |
| 222 | + |
| 223 | +* [Azure Pipelines Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/) |
0 commit comments