Agentless rollback setup and usage (#9419)

* agentless rollbacks pages draft 1

* tidy up setup page and add screenshot

* add pipeline values to list

* update performing a rollback doc

* minor clarifications

* clarify workflow rerun doesn't require GitHub App

Author: rosieyohannan

jekyll/_cci2/deploy/configure-deploy-markers.adoc

@@ -12,9 +12,15 @@ contentTags:
 
 This tutorial shows how to add a deploy marker step to your workflow config. Deploy markers allow you to log all new deployments in one place, update their status and link back to the CI/CD pipelines that triggered them.
 
-Unless you opt out of the feature, CircleCI autodetects potential deployments and creates deploy markers for you. This guide is for you if you would rather create deploy markers yourself. For more information see the xref:deploys-overview#[Deploys overview] page.
+Unless you opt out of the feature, CircleCI autodetects potential deployments and creates deploy markers for you.
 
-Deploy markers provide a lightweight way to log your deployments without requiring a full CircleCI deploys setup. You can use deploy markers independently, without installing the release agent. If you are interested in comprehensive deployment visibility and management features, refer to the xref:set-up-circleci-deploys#[Set up CircleCI deploys] guide for more information.
+This guide is for you if you would rather create deploy markers yourself. For more information see the xref:deploys-overview#[Deploys overview] page.
+
+== Introduction
+
+Autodetected or manually configured deploy markers provide a lightweight way to log your deployments without requiring a you to install the CircleCI release agent. If you install deploy markers manually, as described in this guide you will also be able to use the xref:set-up-rollbacks#[CircleCI rollback feature].
+
+For a full guide to CircleCI's deploys features and functionality, refer to the xref:set-up-circleci-deploys#[Set up CircleCI deploys] guide.
 
 == Prerequisites
 
@@ -123,8 +129,8 @@ jobs:
           name: Update planned release to SUCCESS
           command: |
             circleci run release update \
-              --status=SUCCESS  
-          when: on_success 
+              --status=SUCCESS
+          when: on_success
       - run:
           name: Update planned release to FAILED
           command: |
@@ -134,7 +140,7 @@ jobs:
             circleci run release update \
               --status=FAILED \
               --failure-reason="$FAILURE_REASON"
-          when: on_fail 
+          when: on_fail
 ----
 
 This will update the status of the deploy to `SUCCESS` or `FAILED` depending on the outcome of your job.
@@ -160,13 +166,13 @@ jobs:
     (deploy job steps)
     ...
   cancel-deploy:
-    executor: go  
-    steps:                 
+    executor: go
+    steps:
       - run:
           name: Update planned release to CANCELED
           command: |
             circleci run release update \
-              --status=CANCELED         
+              --status=CANCELED
 ----
 
 Then you can add it to your workflow as shown below.
@@ -180,7 +186,7 @@ workflows:
       - cancel-deploy:
           requires:
             - deploy:
-              - canceled         
+              - canceled
 ----
 
 This will make it sot that the job will be run only when the `deploy` job is canceled, thus updating the deployment to the `canceled` status.
@@ -214,8 +220,8 @@ jobs:
           name: Update planned deployment to SUCCESS
           command: |
             circleci run release update \
-              --status=SUCCESS  
-          when: on_success 
+              --status=SUCCESS
+          when: on_success
       - run:
           name: Update planned deployment to FAILED
           command: |
@@ -225,23 +231,23 @@ jobs:
             circleci run release update \
               --status=FAILED \
               --failure-reason="$FAILURE_REASON"
-          when: on_fail       
+          when: on_fail
   cancel-deploy:
-    executor: go  
-    steps:                 
+    executor: go
+    steps:
       - run:
           name: Update planned release to CANCELED
           command: |
             circleci run release update \
-              --status=CANCELED     
+              --status=CANCELED
 workflows:
   deploy-workflow:
     jobs:
       - deploy
       - cancel-deploy:
           requires:
             - deploy:
-              - canceled 
+              - canceled
 ----
 
 == 2. Deploy logs
@@ -292,13 +298,13 @@ To manually create an environment integration, follow these steps:
 . In the CircleCI web app, select **Deploys** in the sidebar.
 . If this is your first environment setup, select btn:[Create your first Environment Integration]. If you already have environments set up, choose the **Environments** tab and select btn:[Create Environment Integration].
 . Enter a name for your environment, and a description if you would like.
-. Use the dropdown menu to choose your environment integration type, then select btn:[Next: Release Agent Setup]. 
+. Use the dropdown menu to choose your environment integration type, then select btn:[Next: Release Agent Setup].
 If you plan to only use deploy markers, as opposed to the Kubernetes agent, feel free to choose the `custom` type.
 **You do not need to continue with installing a release agent at this point**, but you will need to reference this environment integration name as part of your config when adding the `log release` step below.
 
 == Next steps
 
-By following the steps in this guide, you have added a deploy marker to your CircleCI configuration. 
+By following the steps in this guide, you have added a deploy marker to your CircleCI configuration.
 You can now track the status of your deployments across your configured environments in the CircleCI deploys UI and in the project home page.
 You can now:
 

jekyll/_cci2/deploy/deploys-overview.adoc

@@ -20,7 +20,7 @@ When setting up deploys you can choose one of two options:
 
 * *Release agent*: Choose to use the CircleCI release agent, which you install in your cluster to enable you to manage your deployments through CircleCI.
 
-* *Agentless*: Add CLI commands to your config to enable logging and tracking of deploys and deployment status in the CircleCI UI.
+* *Agentless*: Add CLI commands to your config to enable logging and tracking of deploys and deployment status in the CircleCI UI. Use rollbacks to rollback to a previous version of a component.
 
 If you choose the release agent approach, you will have access to the following deploy management tools from CircleCI:
 

jekyll/_cci2/deploy/rollback-a-project-by-workflow-rerun.adoc

@@ -0,0 +1,44 @@
+---
+contentTags:
+  platform:
+  - Cloud
+---
+= Rollback a project by workflow rerun
+:page-layout: classic-docs
+:page-liquid:
+:page-description:
+:icons: font
+:experimental:
+
+This guides covers how to rollback a project by workflow rerun.
+
+== Prerequisites
+
+Before performing a rollback by workflow rerun, ensure you have configured deploy markers in your CircleCI workflows. Deploy markers track when deployments occur and are essential for rollback functionality. Follow the xref:configure-deploy-markers#[Configure Deploy Markers] guide to set this up. Autodetected deploy markers are *not* supported for use with rollbacks.
+
+== Performing a rollback by workflow rerun
+
+Workflow rerun rollbacks do not need any additional configuration beyond setting up deploy markers. To perform a rollback using workflow rerun:
+
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
+. Select the *Overview* link for your project.
+. Select btn:[Rollback].
+. Select btn:[Rollback by workflow re-run].
+
+.Rollback options on project overview page
+image::deploy/project-overview-rollback.png[Rollback button on project overview page]
+
+This will open the workflow re-run modal with the following options:
+
+* *Choose a version*. Select the version you want to roll back to from the list of available versions.
+* *Confirm rollback*. Select btn:[Next], confirm rollback to proceed.
+
+The workflow that originally deployed the selected version will be re-run, effectively performing a rollback to that version.
+
+=== Important considerations
+
+* *Advantage*: No setup required. This rollback method works immediately after configuring deploy markers.
+* *Disadvantage*: The entire workflow will be re-run, which may not always be desirable depending on your workflow complexity and duration
+* For complete control over the rollback process and to avoid re-running entire workflows, consider using the custom rollback pipeline approach described in the Setting Up Rollbacks in CircleCI section.
+

jekyll/_cci2/deploy/rollback-a-project-using-the-rollback-pipeline.adoc

@@ -0,0 +1,58 @@
+---
+contentTags:
+  platform:
+  - Cloud
+---
+= Rollback a project using the rollback pipeline
+:page-layout: classic-docs
+:page-liquid:
+:page-description:
+:icons: font
+:experimental:
+
+This guide covers how to rollback a project using the rollback pipeline.
+
+== Prerequisites
+
+Before performing a rollback, ensure you have completed the rollback setup process and merged the rollback configuration pull request.
+
+== Performing a Rollback
+
+To perform a rollback using the rollback pipeline follow these steps::
+
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
+. Select the *Overview* link for your project.
+. Select btn:[Rollback].
+. Select btn:[Rollback by running rollback pipeline]. This opens the rollback execution modal.
++
+image::deploy/rollback-execution-modal.png[Rollback execution modal]
++
+The modal displays several configuration options with parameters auto-filled based on your rollback configuration. The following sections explain each required property:
++
+* *Component Name*. This is the name of the component you wish to rollback. If your project deploys multiple components, this helps you choose a specific component you want to rollback.
+* *Environment Name*. This is the environment in which you wish to perform the rollback.
+* *Current Version*. Once you choose the component name and environment name, this will display all possible current versions. More often than not there should be just one current version available. You could have two in case a new progressive release is ongoing. Choose the version you believe is the current version of your component. To help you out, the relevant commit information is also displayed alongside the version.
+* *Target Version*. Choose the version you wish to rollback to. To help you out, the relevant commit information is also displayed alongside the version.
+* *Namespace*. This is optional. In case you use Kubernetes and do your deployments to a specific namespace, mention your namespace here, otherwise leave it empty.
++
+The Parameters section shows the auto-filled parameters from your configuration file, which you can modify as needed for the specific rollback operation.
+
+. *Execute*. Select btn:[Rollback] to trigger the rollback pipeline
+
+The rollback pipeline will now execute and perform the rollback operation according to your configuration.
+
+== Change Rollback Pipeline
+
+If you have configured a new pipeline and want to trigger this pipeline when performing rollbacks, you can change which pipeline is used for rollback operations.
+
+To select a different pipeline for rollbacks, follow these steps:
+
+. Navigate to your project's Overview page.
+. Go to Settings.
+. Select the Deploys tab.
+. In the Rollback Pipeline section, choose the pipeline you want to be selected as the rollback pipeline from the dropdown.
+
+This process allows you to switch between different rollback pipeline configurations as needed for your project.
+
+

jekyll/_cci2/deploy/set-up-rollbacks.adoc

@@ -0,0 +1,108 @@
+---
+contentTags:
+  platform:
+  - Cloud
+---
+= Set up rollbacks in CircleCI
+:page-layout: classic-docs
+:page-liquid:
+:page-description:
+:icons: font
+:experimental:
+
+Rollbacks allow you to quickly revert your application to a previous stable version when issues are detected in production. This guide covers how to configure your CircleCI pipeline to support manual rollback capabilities.
+
+== Prerequisites
+
+* A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free].
+* A CircleCI project with a workflow configured to deploy your code.
+* Read through the xref:deploys-overview#[CircleCI deploys overview] guide.
+
+== Set up rollbacks
+
+=== 1. Manually configure deploy markers
+If not already set up, you must configure deploy markers in your CircleCI workflows. Deploy markers track when deployments occur and are essential for rollback functionality. Follow the xref:configure-deploy-markers#[Configure Deploy Markers] guide to set this up. Autodetected deploy markers are *not* supported for use with rollbacks.
+
+The rest of this guide covers how to set up rollbacks using a custom rollback pipeline. At this point, after deploy markers are configured, you can use the xref:rollback-a-project-by-workflow-rerun#[Rollback by workflow rerun] method.
+
+=== 2. Navigate to project overview
+
+. In the CircleCI dashboard, navigate to *Organization Home* from the sidebar.
+. Select the *Overview* link for your project.
+
+You will see a red Rollback button with a dropdown option on the project overview page.
+
+.Rollback options on project overview page
+image::deploy/project-overview-rollback.png[Rollback button on project overview page]
+
+=== 2. Start the rollback setup
+
+. Select the btn:[Rollback] dropdown.
+. Select *Set up custom rollback pipeline* from the dropdown menu. This launches the rollback setup wizard.
++
+NOTE: To use the rollback by pipeline method, your organization must be connected to the *CircleCI GitHub App*. If the GitHub App is not installed in your org, the rollback setup process will automatically prompt you to install it during setup.
+
+The setup wizard guides you through configuring your custom rollback pipeline.
+
+image::deploy/set-up-a-rollback-pipeline.png[Set up a rollback pipeline]
+
+=== 3. Configure the rollback pipeline
+
+. From the "What repo are you deploying?" dropdown, select the repository you want to create rollbacks for.
+. Select *Create pipeline definition* to proceed.
+
+CircleCI creates a pipeline definition called rollback-pipeline and use the selected repository to store your rollback configuration.
+
+=== 4. Review the generated configuration
+After creating the pipeline definition, the modal will display a pre-generated configuration file for performing rollbacks.
+
+. Review the generated YAML configuration template to ensure you understand the rollback pipeline.
+. Select btn:[Commit Config] to create this rollback configuration template in your repository. The configuration will be committed to a new branch called `rollback-pipeline-setup` in your selected repository.
+
+This config is a template rollback pipeline that includes the following:
+
+* *Parameters section*: Placeholder parameters that you can customize for your specific deployment needs
+* *Jobs section*: A basic rollback job structure with common rollback configuration setups included (but commented out)
+
+After committing, you can modify the configuration according to your needs by setting your own parameters and rollback logic. You can uncomment the included common rollback setups or write your own custom rollback implementation.
+
+=== 5. Create pull request
+After committing the configuration template, the final step is to create a pull request:
+
+. Select btn:[Create PR] to generate a pull request with your rollback configuration.
++
+image::deploy/rollback-create-pr.png[Create PR for rollback pipeline]
+. Navigate to the pull request in your repository and modify the rollback configuration according to your specific deployment needs.
+. Once you have customized the configuration, merge the pull request to complete the rollback setup.
+
+CAUTION: Until the pull request is merged, the rollback setup will not be complete and rollback functionality will not be available.
+
+==== Configuration tips
+
+When customizing your rollback configuration, you can use the following pipeline values to access rollback values:
+
+* `pipeline.deploy.component_name`
+* `pipeline.deploy.environment_name`
+* `pipeline.deploy.target_version`
+* `pipeline.deploy.namespace`
+
+==== Deploy markers for rollbacks
+You can use deploy markers with the `--rollback` flag to indicate rollback deployment:
+
+[source,bash]
+----
+circleci run release plan \
+          --environment-name=${ENVIRONMENT_NAME} \
+          --namespace=${NAMESPACE} \
+          --component-name=${COMPONENT_NAME} \
+          --target-version=${TARGET_VERSION} \
+          --rollback
+----
+
+You can also update the status of the rollback deployment as mentioned in the xref:configure-deploy-markers#[Configure Deploy Markers] guide to reflect the state of the rollback accurately in the CircleCI UI.
+
+=== 6. Access rollback functionality
+Once the pull request is merged, the rollback setup is complete. You can now use the rollback functionality in the CircleCI UI. For a full guide, see the xref:rollback-a-project-using-the-rollback-pipeline#[Rollback a project using the rollback pipeline] guide.
+
+
+

jekyll/_data/sidenav.yml

@@ -376,26 +376,34 @@ en:
     children:
       - name: Overview
         children:
-          - name: Deploys overview
-            link: deploy/deploys-overview
           - name: Overview of deployment on CircleCI
             link: deployment-overview
-      - name: Set up
+          - name: CircleCI deploys overview
+            link: deploy/deploys-overview
+      - name: Set up - Release agent
         children:
           - name: Set up CircleCI deploys
             link: deploy/set-up-circleci-deploys
           - name: Manual install - Set up the release agent
             link: deploy/set-up-the-release-agent
           - name: Manual install - Configure your Kubernetes components
             link: deploy/configure-your-kubernetes-components
-      - name: How to
-        children:
+          - name: Update the Kubernetes release agent
+            link: deploy/update-the-kubernetes-release-agent
           - name: Manage deploys
             link: deploy/manage-deploys
+      - name: Set up - Agentless
+        children:
           - name: Configure deploy markers
             link: deploy/configure-deploy-markers
-          - name: Update the Kubernetes deploy agent
-            link: deploy/update-the-kubernetes-release-agent
+          - name: Set up rollbacks in CircleCI
+            link: deploy/set-up-rollbacks
+          - name: Rollback a project using the rollback pipeline
+            link: deploy/rollback-a-project-using-the-rollback-pipeline
+          - name: Rollback a project by workflow rerun
+            link: deploy/rollback-a-project-by-workflow-rerun
+      - name: How to
+        children:
           - name: Deploy to Amazon SageMaker
             link: deploy-to-amazon-sagemaker
           - name: Deploy Android applications