CI/CD V2 endpoints

umbraco-cloud/set-up/project-settings/umbraco-cicd/ArtifactBestPractice.md

@@ -0,0 +1,31 @@
+# Deployment Artifact best practice
+The zip package you are deploying needs to contain all things that normally is present in an Umbraco Cloud environment-repository.
+
+Every new Umbraco Cloud project contains a readme.md file which explains the structure and how you can adapt it to suit your needs.
+
+The sample scripts on GitHub includes a way to package the zip. As the scripts are samples they show a universal way to do this which works well for most people. But not all projects are alike, and you may not want to use that particular approach.
+
+## Do not include Dotnet Binaries
+Don’t include any binary build artifacts coming from the DotNet build/publish process. 
+
+The general deployment process on Umbraco Cloud needs the source code and the system will rebuild it once it is pushed back to the environment.
+
+## Do not include the .git directory
+The folder will be ignored in the isolated instance, including the extra megabytes will slow down the deployment process. 
+
+Also consider the artifact size limitation below. 
+
+## Do include the finished frontend assets
+If you are using modern frontend build tools, ideally only include the finished frontend assets that are needed. No need to include JavaScript or TypeScript source files if you need to build the frontend. 
+
+## Keep the Artifact as small as possible
+It is good practice to keep the zipped artifact as small as possible. 
+* Large files will slow down the underlying git operations and therefore also the deployment process.
+  * Do not include large files like pictures and pdf’s in the artifact. 
+  * Large files need to be uploaded to the blob storage connected to your environment. 
+* Remove old and leftover code from the artifact. 
+  * Orphaned Csproj-files with outdated package-references are common causes for issues in the deployment process.
+
+Size limitations to consider:
+- The V1 endpoint will allow file sizes up to 128 MB. 
+- In the V2 endpoint we have increased the size limit to 256 MB. 

umbraco-cloud/set-up/project-settings/umbraco-cicd/KnownLimitationsAndConsiderations.md

@@ -2,10 +2,6 @@
 
 As we continue to gather insights from our users, there are some known limitations and considerations to be aware of.
 
-{% hint style="info" %}
-Attaching a CI/CD pipeline to a flexible environment is currently not possible. The CI/CD workflow must go through the mainline deployment workflow.
-{% endhint %}
-
 ## Potential Limitations and Considerations
 
 **Format Restrictions**

umbraco-cloud/set-up/project-settings/umbraco-cicd/Migrate.md

@@ -0,0 +1,112 @@
+# Migrate from V1 to V2
+We wanted to improve on the original flow based on all the feedback received from users of the feature.
+
+Here we will go through how to migrate from V1 samples to V2 samples. 
+
+{% hint style="info" %}
+Be advised that both scripts and pipeline files have changes.
+
+Familiarize you self with the new samples.
+
+If you customized the flow or the V1 scripts please take extra care to incorporate your changes. 
+{% endhint %}
+
+You keep using the old endpoints and samples, but you will miss out on the enhancements.  We currently don't have any plans to deprecate the V1 endpoints.
+
+## What has changed?
+The biggest enhancement is the ability to target different environments. You are now able to target the flexible and the leftmost mainline environment. 
+We have created new endpoints to accommodate this enhancement, meaning you will have to supply a target environment alias in some requests.
+
+Also the initial flow has been slightly changed. The upload of a deployment package is no longer tied to a "deployment-meta", but is now a separate step. Every uploaded artifact can be queried by the api, similar to querying deployments via the api. 
+
+When you request a deployment you now also need to supply an artifactId. Also more options are available when deploying.
+
+To showcase how to use the new V2 endpoints and flow, we have created some updated samples.  
+
+# Migrate Azure DevOps
+Start by deleting the scripts and yaml files you initially got from the CI/CD samples:
+- Delete the Yaml/yml:
+  - `azure-release-pipeline.yaml`
+  - `cloud-sync.yml`
+  - `cloud-deployment.yml`
+
+You probably only have either PowerShell or Bash.
+- PowerShell files to delete:
+  - `Add-DeploymentPackage.ps1`
+  - `Apply-Patch.ps1`
+  - `Get-ChangesById.ps1`
+  - `Get-LatestDeployment.ps1`
+  - `New-Deployment.ps1`
+  - `Start-Deployment.ps1`
+  - `Test-Deployment.ps1`
+- Bash files to delete:
+  - `apply_patch.sh`
+  - `create_deployment.sh`
+  - `get_changes_by_id.sh`
+  - `get_deployment_status.sh`
+  - `get_latest_deployment.sh`
+  - `start_deployment.sh`
+  - `upload_package.sh`
+
+Now copy the scripts from the sample repositorys V2 folder to the corresponding folder in you repo:
+- If you prefer PowerShell:
+  - All .ps1 files in `V2/powershell` should be copied to `devops/powershell`
+  - All .yaml/.yml in `V2/powershell/azuredevops` should be copied to `devops` 
+- If you prefer Bash:
+  - All .sh files in `V2/bash` should be copied to `devops/scripts`
+  - All .yaml/.yml in `V2/bash/azuredevops` should be copied to `devops` 
+
+Now we need some important values: Project id and Target environment alias.
+- [This section](./samplecicdpipeline/README.md#obtaining-the-project-id-and-api-key) explains how to get the project id. 
+- [This section](./samplecicdpipeline/README.md#getting-environment-aliases-to-target) explains how to get the environment alias.
+
+Now open the `azure-release-pipeline.yaml` in your favorite editor. 
+You need to replace `##Your project Id here##` with the project Id and the value `##Your target environment alias here#` with the environment alias. 
+
+You can use any of the available aliases, but to get similar functionality as before you should select the environment described as `Leftmost mainline`.
+
+# Migrate GitHub
+Start by deleting the scripts and yaml files you initially got from the CI/CD samples:
+- Delete the Yaml:
+  - `main.yml`
+  - `cloud-sync.yml`
+  - `cloud-deployment.yml`
+
+You probably only have either PowerShell or Bash.
+- PowerShell files to delete:
+  - `Add-DeploymentPackage.ps1`
+  - `Apply-Patch.ps1`
+  - `Get-ChangesById.ps1`
+  - `Get-LatestDeployment.ps1`
+  - `New-Deployment.ps1`
+  - `Start-Deployment.ps1`
+  - `Test-Deployment.ps1`
+- Bash files to delete:
+  - `apply_patch.sh`
+  - `create_deployment.sh`
+  - `get_changes_by_id.sh`
+  - `get_deployment_status.sh`
+  - `get_latest_deployment.sh`
+  - `start_deployment.sh`
+  - `upload_package.sh`
+
+Now copy the scripts from the sample repositorys V2 folder to the corresponding folder in you repo:
+- If you prefer PowerShell:
+  - All .ps1 files in `V2/powershell` should be copied to `.github/powershell`
+  - All .yaml/.yml in `V2/powershell/github` should be copied to `.github/workflows` 
+- If you prefer Bash:
+  - All .sh files in `V2/bash` should be copied to `.github/scripts`
+  - All .yaml/.yml in `V2/bash/github` should be copied to `.github/workflows` 
+
+Now we need one important value: Target environment alias.
+- [This section](./samplecicdpipeline/README.md#getting-environment-aliases-to-target) explains how to get the environment alias.
+
+Go to your GitHub repository and enter the `Settings` section.
+- In the left side menu find the `Security` section and click on `Actions`
+- Click on the tab `Variables`
+- Click on `New repository variable`
+  - Call the variable `TARGET_ENVIRONMENT_ALIAS`
+  - Use the environment alias as value
+- Click on `Add variable`.
+
+You can use any of the available aliases, but to get similar functionality as before you should select the environment described as `Leftmost mainline`.