You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
7
7
8
+
== Introduction
9
+
10
+
CircleCI rollbacks support two methods: Rollback by running a custom rollback pipeline or Rollback by workflow re-run. Each method has appropriate use cases, advantages and disadvantages, as follows:
11
+
12
+
[options="header", cols="1,1,1,1"]
13
+
|===
14
+
|
15
+
|Advantages
16
+
|Disadvantages
17
+
|Applications
18
+
19
+
|*Rollback by running a custom rollback pipeline*
20
+
a| * Fast - Only execute deployment
21
+
* Full control over rollback process
22
+
a| * Requires pipeline setup
23
+
a| * Complex systems
24
+
* Time-critical requirements
25
+
* Multi-component app deployments
26
+
27
+
|*Rollback by workflow re-run*
28
+
a| * No pipeline setup required
29
+
a| * Limited control over rollback process
30
+
* Full workflow is rerun
31
+
* Slower execution
32
+
a| * Simple systems
33
+
* Need immediate rollback
34
+
|===
35
+
8
36
== Prerequisites
9
37
10
38
* A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free].
11
39
* A CircleCI project with a workflow configured to deploy your code.
12
-
* Read through the xref:deploys-overview.adoc[CircleCI deploys overview] guide.
40
+
* Deploy markers *must* be configured in your project. Follow the xref:configure-deploy-markers.adoc[Configure Deploy Markers] guide to set this up. Autodetected deploy markers are *not* supported for use with rollbacks.
41
+
* Familiarity with CircleCI deploys concepts. Find full details in the xref:deploys-overview.adoc[CircleCI deploys overview] guide.
13
42
14
43
== Set up rollbacks
15
44
16
-
=== 1. Manually configure deploy markers
17
-
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.adoc[Configure Deploy Markers] guide to set this up. Autodetected deploy markers are *not* supported for use with rollbacks.
18
-
19
-
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.adoc[Rollback by workflow rerun] method.
45
+
The following steps guide you through setting up a custom rollback pipeline. This is the recommended rollback method.
20
46
21
-
=== 2. Navigate to project overview
47
+
=== 1. Navigate to project overview
22
48
23
49
. In the CircleCI dashboard, navigate to *Organization Home* from the sidebar.
24
50
. Select the *Overview* link for your project.
@@ -28,6 +54,8 @@ You will see a red Rollback button with a dropdown option on the project overvie
28
54
.Rollback options on project overview page
29
55
image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on project overview page]
30
56
57
+
The followng 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.
58
+
31
59
=== 2. Start the rollback setup
32
60
33
61
. Select the btn:[Rollback] dropdown.
@@ -42,9 +70,9 @@ image::guides:ROOT:deploy/set-up-a-rollback-pipeline.png[Set up a rollback pipel
42
70
=== 3. Configure the rollback pipeline
43
71
44
72
. From the "What repo are you deploying?" dropdown, select the repository you want to create rollbacks for.
45
-
. Select *Create pipeline definition* to proceed.
73
+
. Select btn:[Create pipeline definition] to proceed.
46
74
47
-
CircleCI creates a pipeline definition called rollback-pipeline and use the selected repository to store your rollback configuration.
75
+
CircleCI creates a pipeline definition called `rollback-pipeline` and uses the selected repository to store your rollback configuration.
48
76
49
77
=== 4. Review the generated configuration
50
78
After creating the pipeline definition, the modal will display a pre-generated configuration file for performing rollbacks.
@@ -57,15 +85,15 @@ This config is a template rollback pipeline that includes the following:
57
85
* *Parameters section*: Placeholder parameters that you can customize for your specific deployment needs
58
86
* *Jobs section*: A basic rollback job structure with common rollback configuration setups included (but commented out)
59
87
60
-
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.
61
-
62
88
=== 5. Create pull request
63
-
After committing the configuration template, the final step is to create a pull request:
89
+
After committing the configuration template, you can create a pull request from the CircleCI UI:
64
90
65
91
. Select btn:[Create PR] to generate a pull request with your rollback configuration.
66
92
+
67
93
image::guides:ROOT:deploy/rollback-create-pr.png[Create PR for rollback pipeline]
68
-
. Navigate to the pull request in your repository and modify the rollback configuration according to your specific deployment needs.
94
+
. Navigate to the pull request in your repository and modify the rollback configuration according to your specific deployment needs, for example, you can:
95
+
** Set your own parameters and rollback logic.
96
+
** Uncomment the included common rollback setups or write your own custom rollback implementation.
69
97
. Once you have customized the configuration, merge the pull request to complete the rollback setup.
70
98
71
99
CAUTION: Until the pull request is merged, the rollback setup will not be complete and rollback functionality will not be available.
@@ -97,4 +125,76 @@ circleci run release plan \
97
125
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.
98
126
99
127
=== 6. Access rollback functionality
100
-
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.adoc[Rollback a project using the rollback pipeline] guide.
128
+
Once the pull request is merged, the rollback setup is complete. You can now use the rollback functionality in the CircleCI UI.
129
+
130
+
== Perform a rollback
131
+
132
+
To perform a rollback using the rollback pipeline follow these steps:
133
+
134
+
. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
135
+
. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
136
+
. Select the *Overview* link for your project.
137
+
. Select btn:[Rollback].
138
+
. Select btn:[Rollback by running rollback pipeline]. This opens the 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:
143
+
+
144
+
*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.
145
+
*Environment Name*:: This is the environment in which you wish to perform the rollback.
146
+
*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.
147
+
*Target Version*:: Choose the version you wish to rollback to. To help you out, the relevant commit information is also displayed alongside the version.
148
+
*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.
149
+
+
150
+
The Parameters section shows the auto-filled parameters from your configuration file, which you can modify as needed for the specific rollback operation.
151
+
152
+
. *Execute*. Select btn:[Rollback] to trigger the rollback pipeline
153
+
154
+
The rollback pipeline will now execute and perform the rollback operation according to your configuration.
155
+
156
+
== Change Rollback Pipeline
157
+
158
+
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.
159
+
160
+
To select a different pipeline for rollbacks, follow these steps:
161
+
162
+
. Navigate to your project's Overview page.
163
+
. Go to Settings.
164
+
. Select the Deploys tab.
165
+
. In the Rollback Pipeline section, choose the pipeline you want to be selected as the rollback pipeline from the dropdown.
166
+
167
+
This process allows you to switch between different rollback pipeline configurations as needed for your project.
168
+
169
+
170
+
== Rollback by workflow re-run
171
+
172
+
Workflow rerun rollbacks do not need any additional configuration beyond setting up deploy markers. There are advantages and disadvantages to using this method, as follows:
173
+
174
+
* *Advantage*: No setup required. This rollback method works immediately after configuring deploy markers.
175
+
* *Disadvantage*: The entire workflow will be re-run, which may not always be desirable depending on your workflow complexity and duration.
176
+
177
+
The Rollback by workflow re-run method is only recommended for simple deployments. For complete control over the rollback process and to avoid re-running entire workflows, consider using the custom rollback pipeline approach described above.
178
+
179
+
To perform a rollback using workflow rerun:
180
+
181
+
. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
182
+
. Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
183
+
. Select the *Overview* link for your project.
184
+
. Select btn:[Rollback].
185
+
. Select btn:[Rollback by workflow re-run].
186
+
187
+
.Rollback options on project overview page
188
+
image::guides:ROOT:deploy/project-overview-rollback.png[Rollback button on project overview page]
189
+
190
+
This will open the workflow re-run modal with the following options:
191
+
192
+
* *Choose a version*. Select the version you want to roll back to from the list of available versions.
193
+
* *Confirm rollback*. Select btn:[Next], confirm rollback to proceed.
194
+
195
+
The workflow that originally deployed the selected version will be re-run, effectively performing a rollback to that version.
0 commit comments