From 648f1cd8518a61a585c7322f9b6e2e0e9d17ca30 Mon Sep 17 00:00:00 2001 From: Sofie Toft Date: Wed, 27 Aug 2025 19:37:19 +0200 Subject: [PATCH 1/5] Clean some articles --- .../samplecicdpipeline/azure-devops.md | 2 ++ .../samplecicdpipeline/github-actions.md | 4 +++ .../umbraco-cicd/troubleshooting.md | 18 +++++------ .../umbraco-cicd/umbracocloudapi.md | 30 +++++++++++-------- 4 files changed, 32 insertions(+), 22 deletions(-) diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md index 2f2ee34089c..8ac91d91bfe 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md @@ -234,7 +234,9 @@ If you want to customize the artifact take a look at [Artifact Best Practice](.. The `cloud-deployment.yml` shows how you can deploy to a named environment of your Cloud project. The sample shows how to request the deployment and wait for cloud to finish the operation. {% hint style="info" %} + If you have frontend assets that needs to be built (using tools like npm/yarn or others), you should add the needed steps before `cloudPrepareArtifact`. This is to ensure that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud. + {% endhint %} ## Next step diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md index fd22393e23c..09acc8c9a15 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md @@ -83,6 +83,7 @@ Now go to the **Variables** tab * Create a `repository variable` called `TARGET_ENVIRONMENT_ALIAS` and enter the environment alias you selected earlier. {% hint style="info" %} + If you want to use other names for the secrets and variables, you need to rename the `secrets` and `with` variables in each of `main.yml`'s jobs. ```yaml @@ -110,6 +111,7 @@ jobs: with: targetEnvironmentAlias: ${{ vars.TARGET_ENVIRONMENT_ALIAS }} # change the part inside the curly braces ``` + {% endhint %} Now GitHub is set up with the needed information to be able to run a deployment back to Umbraco Cloud. @@ -264,7 +266,9 @@ If you want to customize the artifact take a look at [Artifact Best Practice](.. The `cloud-deployment.yml` shows how you can deploy to a named environment of your Cloud project. The sample shows how to request the deployment and wait for cloud to finish the operation. {% hint style="info" %} + If you have frontend assets that needs to be built (using tools like npm/yarn or others), you should add the needed steps before `cloud-artifact`. This is to ensure that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud. + {% endhint %} ## Next step diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md index def34ad0e7f..48aa2afae65 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md @@ -26,7 +26,7 @@ The mechanism to determine changes since the last deployment is not able to do s } ``` -You will need to _manually_ make sure that all latest changes on your left-most mainline environment in cloud is also present in your local copy. +You need to _manually_ make sure that all latest changes on your left-most mainline environment is also present in your local copy. Once this is done you can run a new deployment, where you skip the cloud-sync step. @@ -58,8 +58,8 @@ Once that has been done, you should run a new deployment without the `cloud-sync For Azure DevOps, see the [Skip cloud-sync in Azure DevOps](troubleshooting.md#skip-cloud-sync-in-azure-devops) section. 1. Ensure your GitHub repository is up-to-date with any changes in your Umbraco Cloud environment. -2. Locate the main.yml file in the following directory: {projectname}.github\workflows on tour local project. -3. Open the main.yml file in a text editor and navigate to the “jobs” section. +2. Locate the `main.yml` file in the following directory: `{projectname}.github\workflows` on tour local project. +3. Open the `main.yml` file in a text editor and navigate to the “jobs” section. 4. Comment out the entire “cloud-sync” section and the “needs: cloud-sync” under “cloud-deployment”. An example is provided in the screenshot below. ![Cloud sync code highlight](../../set-up-your-project/project-settings/images/cloudsync.png) @@ -108,11 +108,11 @@ You can see an example of how you could zip your repository before uploading it, ## Deployment failed -### File missing: The .umbraco file cannot be found in the root of the repository +### File missing: The `.umbraco` file cannot be found in the root of the repository The `.umbraco` file is missing or has been renamed. This file needs to be present in the root of the zipped package. -### File format Error: The .umbraco file is not valid +### File format Error: The `.umbraco` file is not valid The `.umbraco` file has invalid characters. Sometimes people need to change the repository's folder structure and the default project's name. Ensure that the base field does not use backslashes ('') as the folder denominator. @@ -142,7 +142,7 @@ We recommend aligning the package versions in your _.csproj_ files with the high If you have orphaned csproj-files you should remove them or rename them. Orphaned would be backup _.csproj_ files or files not referenced by any of the main project files nor referenced in a _.sln_ file. -### Could not find '/app/work/repository/Readme.md' to stat: No such file or directory +### Could not find `/app/work/repository/Readme.md` to stat: No such file or directory In some instances we see an issue where filename casing is causing an error. @@ -170,18 +170,18 @@ Once the marker file is removed, run your pipeline again. ### Unable to determine environment by its {environment-id} -This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: +This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: ``` “System.InvalidOperationException: Unable to determine environment by its {environment-id}” ``` -This issue arises because the environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps: +This issue arises because the environment is missing in the local `umbraco-cloud.json` file. To resolve this issue, follow these steps: 1. Navigate to Kudu in your Live environment 2. Select “Debug console” and choose “CMD”. 3. Find the umbraco-cloud.json file. Path to this file may vary depending on your setup, but the default location on cloud is C:\home\site\repository\src\UmbracoProject 4. Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so. -5. Paste the copied content into the umbraco-cloud.json file in your local project and push the changes. +5. Paste the copied content into the `umbraco-cloud.json` file in your local project and push the changes. After completing these steps, your left-most mainline environment should be correctly registered across all environments, allowing you to continue your work without any issues. diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md index e757ba72289..ed6a4d2a931 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md @@ -2,9 +2,8 @@ The Umbraco Cloud API serves as a publicly accessible endpoint that customers can utilize to execute relevant tasks. -While its initial focus is on automating and managing deployments in Umbraco Cloud projects via the "Umbraco CI/CD Flow," future enhancements will broaden its capabilities to encompass a wider range of activities and options for Umbraco Cloud users. - {% hint style="info" %} + ### Changes between endpoints for version 1 and 2 With the endpoints for version 2, you are given more control over the process. @@ -17,7 +16,8 @@ These are the most important differences between the V1 and V2 endpoints: [Do you want to migrate from V1 to V2 endpoints?](samplecicdpipeline/migrate.md) -The V1 endpoints are still available, you can see the [V1 api documentation here](v1-umbraco-cloud-api.md). +[The V1 endpoints are still available](v1-umbraco-cloud-api.md). + {% endhint %} ## Getting started @@ -53,8 +53,9 @@ The two elements to be used for the authentication are: By including the API key header in your HTTP requests, you ensure secure access to your Umbraco Cloud project's resources. -For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions.\ -It's important to note that each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project. +For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions. + +Each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project. ### How to authenticate your requests @@ -231,16 +232,16 @@ The response from the API should be an HTTP 201 Created response including a `de You can use the deploymentId to query the Get Deployment status endpoint. {% hint style="info" %} -It is not recommended to enable the `skipVersionCheck`. This is to ensure that versions of the various Umbraco packages in the Cloud environment aren't overwritten by older versions. However, there may be instances where you would like to deploy an older artifact, and for those cases, it is possible to enable this setting to skip the step. +It is not recommended to enable the `skipVersionCheck`. This is to ensure that versions of the different Umbraco packages in the Cloud environment aren't overwritten by older versions. There may be instances where you would like to deploy an older artifact. In those instances it is possible to enable this setting to skip the step. -Enabling the `noBuildAndRestore` only disabled the restore and build inside the isolated instance. Once the system pushes the source code to the environment, the regular Cloud flow takes over, and a build and publish operation will run as usual. One minute or more can be saved during the deployment process by enabling this option. +Enabling the `noBuildAndRestore` only disabled the restore and build inside the isolated instance. Once the system pushes the source code to the environment a build and publish operation will run as usual. One minute or more can be saved during the deployment process by enabling this option. {% endhint %} ### Get Deployment status -To monitor the status of a deployment, you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API, and it requires both the `projectId` and the `deploymentId` obtained from previous steps to be included in the path. +To monitor the status of a deployment, you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API. It requires both the `projectId` and the `deploymentId` obtained from previous steps to be included in the path. -Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, in a simple project, you might choose to poll the API every 25 seconds for a duration of 15 minutes. These figures are just a starting point; the optimal polling frequency and duration may differ for your specific pipeline. +Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, you might choose to poll the API every 25 seconds for a duration of 15 minutes. These figures are a starting point. The optimal polling frequency and duration may differ for your specific pipeline. A new query parameter has been added to limit the deploymentStatusMessages. As a value for the query parameter you can use the `modifiedUtc` value from a previous response. @@ -257,7 +258,8 @@ Umbraco-Cloud-Api-Key: {{apiKey}} Content-Type: application/json ``` -The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the `deploymentState` field will indicate either 'Completed' or 'Failed'.\ +The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the `deploymentState` field will indicate either 'Completed' or 'Failed'. + Should the deployment fail, check the `deploymentStatusMessages` for more information. ```json @@ -353,15 +355,17 @@ Content-Type: application/json ``` -The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. On the other hand, if there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes. +The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. If there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes. {% hint style="info" %} -It is only possible to generate git-patch files when the selected `deploymentId` points to a deployment where the `targetEnvironmentAlias` then, is the same as in this request. + +It is only possible to generate git-patch files when the selected `deploymentId` points to a deployment where the `targetEnvironmentAlias` is the same as in this request. + {% endhint %} ## Possible errors -When interacting with the Umbraco Cloud API, you may encounter various HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting: +When interacting with the Umbraco Cloud API, you may encounter HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting: | Status Code | Error | Basic Root Cause | | ----------- | ------------------- | ----------------------------------------------------------------------------------- | From 4201e3015b0d278f044f31ac282e36ca9e3e17a7 Mon Sep 17 00:00:00 2001 From: Sofie Toft Date: Wed, 27 Aug 2025 19:51:17 +0200 Subject: [PATCH 2/5] Add tests for vale --- .../umbraco-cicd/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md index 48aa2afae65..d59ac363492 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md @@ -164,7 +164,7 @@ In order to fix this issue, you need to use [KUDU](../../../optimize-and-maintai 3. Navigate to `site` > `locks` folder In there, there should be a file named `updating` 4. Remove the `updating` file. -Once the marker file is removed, run your pipeline again. +Once the marker file is removed, run your pipeline again. Testing here and read more. ## Environment errors after deployment From 0d64689058f89aa4dc409e11e7f485807b6197e5 Mon Sep 17 00:00:00 2001 From: Sofie Toft Date: Thu, 28 Aug 2025 08:48:32 +0200 Subject: [PATCH 3/5] Add test link --- .../umbraco-cicd/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md index d59ac363492..c6be7b7d6b2 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md @@ -164,7 +164,7 @@ In order to fix this issue, you need to use [KUDU](../../../optimize-and-maintai 3. Navigate to `site` > `locks` folder In there, there should be a file named `updating` 4. Remove the `updating` file. -Once the marker file is removed, run your pipeline again. Testing here and read more. +Once the marker file is removed, run your pipeline again. Testing here and read more. I'm a link to [here](link.md). ## Environment errors after deployment From c118116645c25517f07ebe8a0c56f8dac8e25b15 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 28 Aug 2025 09:10:12 +0200 Subject: [PATCH 4/5] Update umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md --- .../umbraco-cicd/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md index c6be7b7d6b2..ca4848c4932 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md @@ -170,7 +170,7 @@ Once the marker file is removed, run your pipeline again. Testing here and read ### Unable to determine environment by its {environment-id} -This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: +This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: For more info about tests, [click here](www. umbraco.dk) ``` “System.InvalidOperationException: Unable to determine environment by its {environment-id}” From 4ca77193b0e6410c4202cf5f5c026e6266012d48 Mon Sep 17 00:00:00 2001 From: Sofie Toft Date: Thu, 28 Aug 2025 09:33:30 +0200 Subject: [PATCH 5/5] Update vale rule --- .github/styles/UmbracoDocs/LinkTextClarity.yml | 11 +++++++---- .../umbraco-cicd/troubleshooting.md | 4 ++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.github/styles/UmbracoDocs/LinkTextClarity.yml b/.github/styles/UmbracoDocs/LinkTextClarity.yml index dbcec914e4b..ade970ba0fd 100644 --- a/.github/styles/UmbracoDocs/LinkTextClarity.yml +++ b/.github/styles/UmbracoDocs/LinkTextClarity.yml @@ -4,8 +4,11 @@ message: "Avoid generic link text like '%s'. Use descriptive link text instead." description: > Descriptive link text improves accessibility and SEO. level: warning +ignorecase: true +scope: raw +nonword: true tokens: - - 'click here' - - 'read more' - - 'more info' - - '\bhere\b' + - '\[\s*here\s*\]' + - '\[\s*click here\s*\]' + - '\[\s*read more\s*\]' + - '\[\s*more info\s*\]' diff --git a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md index ca4848c4932..48aa2afae65 100644 --- a/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md +++ b/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md @@ -164,13 +164,13 @@ In order to fix this issue, you need to use [KUDU](../../../optimize-and-maintai 3. Navigate to `site` > `locks` folder In there, there should be a file named `updating` 4. Remove the `updating` file. -Once the marker file is removed, run your pipeline again. Testing here and read more. I'm a link to [here](link.md). +Once the marker file is removed, run your pipeline again. ## Environment errors after deployment ### Unable to determine environment by its {environment-id} -This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: For more info about tests, [click here](www. umbraco.dk) +This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: ``` “System.InvalidOperationException: Unable to determine environment by its {environment-id}”