Documenting new guided setup for rollback pipeline

docs/guides/modules/ROOT/nav.adoc

@@ -164,7 +164,7 @@
 ** xref:deploy:deployment-overview.adoc[Deployment and deploy management]
 ** Setup
 *** xref:deploy:configure-deploy-markers.adoc[Configure deploy markers]
-*** xref:deploy:set-up-rollbacks.adoc[Rollbacks]
+*** xref:deploy:set-up-rollbacks.adoc[Rollback a deployment]
 ** Release agent setup
 *** xref:deploy:release-agent-overview.adoc[Release agent overview]
 *** xref:deploy:set-up-the-circleci-release-agent.adoc[Set up the CircleCI release agent]

docs/guides/modules/deploy/pages/set-up-rollbacks.adoc

@@ -1,4 +1,4 @@
-= Set up rollbacks in CircleCI
+= Rollback a deployment
 :page-platform: Cloud
 :page-description:
 :experimental:
@@ -35,101 +35,92 @@ a| * Simple systems
 
 == 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.
-* Deploy markers *must* be configured in your project. Follow the xref:configure-deploy-markers.adoc[Configure Deploy Markers] guide to set this up.
-* Familiarity with CircleCI deploys concepts. Find full details in the xref:deployment-overview.adoc[CircleCI deploys overview] guide.
+- 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.
+- Deploy markers *must* be configured in your project to use CircleCI rollbacks. Follow the xref:configure-deploy-markers.adoc[Configure Deploy Markers] guide to set this up, or if you would rather your will be guided to set up deploy markers when following the <<set-up-a-rollback-pipeline>> guide.
+- Familiarity with CircleCI deploys concepts. Find full details in the xref:deployment-overview.adoc[CircleCI deploys overview] guide.
 
-== Set up rollbacks
+== Set up a rollback pipeline
 
 The following steps guide you through setting up a custom rollback pipeline. Using a custom rollback pipeline is the recommended rollback method.
 
-=== 1. Navigate to project overview
+NOTE: The following steps guide you through setting up a custom rollback pipeline. If you want details on how to *Rollback by workflow re-run*, see the <<rollback-by-workflow-re-run, Rollback by workflow re-run>> section at the end of this guide.
 
-. 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.
+=== 1. Start the rollback pipeline setup
 
-.Rollback options on project overview page
+. In the CircleCI dashboard, navigate to *Organization Home* from the sidebar.
+. Select the menu:Overview[] link for your project.
+. In the menu that appears, select btn:[Create rollback pipeline].
++
 image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on project overview page]
 
-The following steps guide you through setting up a custom rollback pipeline. If you want details on how to *Rollback by workflow re-run*, see the <<rollback-by-workflow-re-run, Rollback by workflow re-run>> section at the end of this guide.
+=== 2. Confirm GitHub App installation
 
-=== 2. Start the rollback setup
+NOTE: To set up rollback pipelines, you must connect your organization to the xref:integration:github-apps-integration.adoc[CircleCI GitHub App].
 
-. Select the btn:[Rollback] dropdown.
-. Select *Set up custom rollback pipeline* from the dropdown menu. This launches the rollback setup wizard.
+- If the GitHub App is not installed in your organization, the guided setup process prompts you to install it.
 +
-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.
+image::guides:ROOT:deploy/install-github-app.png[Install GitHub App]
 
-The setup wizard guides you through configuring your custom rollback pipeline.
+- If the GitHub App is already installed in your organization, the **GitHub App Installation** step is automatically marked as completed.
 
-image::guides:ROOT:deploy/set-up-a-rollback-pipeline.png[Set up a rollback pipeline]
+=== 3. Add deploy markers
 
-=== 3. Configure the rollback pipeline
+Deploy markers *must* be configured in your project to use CircleCI rollbacks. Follow these steps or the xref:configure-deploy-markers.adoc[Configure Deploy Markers] guide to set this up. Or if you already have deploy markers set up, select btn:[I've updated my config] to proceed to the next step.
 
-. From the "What repo are you deploying?" dropdown, select the repository you want to create rollbacks for.
-. Select btn:[Create pipeline definition] to proceed.
+. Expand the **Add deploy markers to existing pipeline** section.
+. In the **Environment Name** dropdown, select or type the xref:configure-deploy-markers#manage-environments[target environment].  If the specified environment does not exist, it will be created. If you do not specify an environment, CircleCI will create one named `default`.
 
-CircleCI creates a pipeline definition called `rollback-pipeline` and uses 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:
+. In the **Component Name** dropdown, select or type the name of the component you want to rollback. The component name sets the name that will be displayed in the Deploys UI.
++
+image::guides:ROOT:deploy/add-deploy-markers-selection.png[Select deploy markers values]
++
+The setup will auto-generate deploy marker commands based on your selections.
+. Copy the generated commands using the btn:[Copy] button and paste them into your existing config file where the deployment occurs. Ensure the `circleci run release plan` step comes before the deployment step, followed by the `circleci run release update` step.
++
+image::guides:ROOT:deploy/auto-generated-commands.png[Generated markers commands]
 
-* *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)
+. Once you have updated your config file, select btn:[I've updated my config] to proceed to the next step.
++
+image::guides:ROOT:deploy/config-updated-button.png[Copy markers commands]
 
-=== 5. Create pull request
-After committing the configuration template, you can create a pull request from the CircleCI UI:
+=== 4. Set up rollback configuration
 
-. Select btn:[Create PR] to generate a pull request with your rollback configuration.
+. Select the repository you want to deploy from the "What repo are you deploying?" dropdown.
 +
-image::guides:ROOT: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, for example, you can:
-** Set your own parameters and rollback logic.
-** Uncomment the included common rollback setups or write your own custom rollback implementation.
-. Once you have customized the configuration, merge the pull request to complete the rollback setup.
+image::guides:ROOT:deploy/select-deploy-repo.png[Select repository]
 
-CAUTION: Until the pull request is merged, the rollback setup will not be complete and rollback functionality will not be available.
+. Review the example config file template. It shows how you will perform rollbacks and how to use deploy markers to track these rollbacks
+. Select btn:[Commit config & create Pull Request] to create this rollback configuration template in your repository. The setup will open a pull request in a new tab with the suggested changes.
++
+NOTE: The configuration will be committed to a new branch called `rollback-pipeline-setup` in the repository you selected .
++
+image::guides:ROOT:deploy/commit-config-button.png[Commit config button]
 
-==== Configuration tips
+. Alternatively, you can copy the suggested configuration into an existing or newly created rollback config file. Make sure the file is called `rollback.yml` and is located in the `.circleci` folder, for the system to detect and use this file. In this case,select btn:[I already have a rollback config] and skip to the next step. See the <<configuration-tips, Configuration tips>> section for more details on customizing your rollback configuration.
++
+image::guides:ROOT:deploy/already-have-config-button.png[Already have config button]
 
-When customizing your rollback configuration, you can use the following pipeline values to access rollback values:
+. You can manually navigate to the pull request by selecting btn:[View pull Request].
++
+image::guides:ROOT:deploy/view-pr-button.png[View pull request button]
 
-* `pipeline.deploy.component_name`
-* `pipeline.deploy.environment_name`
-* `pipeline.deploy.target_version`
-* `pipeline.deploy.current_version`
-* `pipeline.deploy.namespace`
-* `pipeline.deploy.reason`
+. In the pull request in your repository, modify the rollback configuration according to your specific deployment needs. For example: set your own parameters and rollback logic, uncomment the included common rollback setups or write your own custom rollback implementation.
+. Once you have customized the configuration, merge the pull request to complete the rollback setup.
 
-==== 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
-----
+=== 5. Complete rollback setup
 
-You can also update the status of the rollback deployment as mentioned in the xref:configure-deploy-markers.adoc[Configure Deploy Markers] guide to reflect the state of the rollback accurately in the CircleCI UI.
+. After merging the pull request, return to the setup page in the CircleCI web app.
+. Select btn:[Setup rollback pipeline] to activate the rollback pipeline.
++
+image::guides:ROOT:deploy/setup-rollback-pipeline-button.png[Setup rollback pipeline button]
 
-=== 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.
+You can now rollback deployments by running a rollback pipeline.
 
-== Perform a rollback
+== Rollback using a rollback pipeline
 
-To perform a rollback using the rollback pipeline you can select the btn:[Rollback] button on the project overview page or from the deploys UI. The following steps show how to perform a rollback from the project overview page:
+To perform a rollback using the rollback pipeline you can select the btn:[Rollback] button on the project overview page. The following steps show how to perform a rollback from the project overview page:
 
 . 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.
@@ -146,10 +137,11 @@ The modal displays several configuration options with parameters auto-filled bas
 *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*:: Optional. In case you use Kubernetes and do your deployments to a specific namespace, mention your namespace here, otherwise leave it empty.
+*Rollback reason*:: You can optionally provide a reason for the rollback.
 +
 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
+. Select btn:[Rollback] to trigger the rollback pipeline
 
 The rollback pipeline will now execute and perform the rollback operation according to your configuration.
 
@@ -166,16 +158,30 @@ To select a different pipeline for rollbacks, follow these steps:
 
 This process allows you to switch between different rollback pipeline configurations as needed for your project.
 
+== 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.current_version`
+* `pipeline.deploy.namespace`
+* `pipeline.deploy.reason`
+
+For a full list of pipeline values, see the xref:reference:ROOT:variables.adoc#pipeline-values[Pipeline Values] guide.
+
 == Example rollback pipeline configuration
 
 In this section you can find a full example of a rollback pipeline config. This example uses Helm to perform a rollback on AWS EKS and kubectl to validate its status.
 
-****
-*This template assumes the following:*
+[NOTE]
+====
+This template assumes the following:
 
 . Your deployment is annotated with a "version" label.
 . The name of your Helm chart is the same as the name of the component. If this is not the case, you can instead add a label to the deployment with the component name and retrieve it that way
-****
+====
 
 .Example rollback pipeline configuration
 [source,yaml]
@@ -536,5 +542,13 @@ This will open the workflow re-run modal with the following options:
 
 The workflow that originally deployed the selected version will be re-run, effectively performing a rollback to that version.
 
+If you have a rollback pipeline set up for your project, workflow rollbacks are disabled from the project overview page. You can still access this option from the deploys timeline, as follows:
+
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Deploys** from the sidebar and locate your project from the list. You can use the filters and search to help.
+. Select the rollback icon image:guides:ROOT:icons/rebuild.svg[rollback icon, role="no-border"].
+. Select btn:[Rerun deploy workflow from start].
+. Type `ROLLBACK` when prompted to confirm and then select btn:[ROLLBACK].
+