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
Copy file name to clipboardExpand all lines: jekyll/_cci2/migrating-from-1-2.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -62,9 +62,9 @@ If you do not have a `checkout` step, you must add this step to your `config.yml
62
62
63
63
## Steps to Configure Workflows
64
64
65
-
Optionally configure workflows, using the following instructions:
65
+
To increase the speed of your software development through faster feedback, shorter re-runs, and more efficient use of resources, configure workflows using the following instructions:
66
66
67
-
1. To use the Workflows feature for job orchestration, first split your build job into multiple jobs, each with a unique name.
67
+
1. To use the Workflows feature, split your build job into multiple jobs, each with a unique name. It might make sense to start by just splitting out a deploy job to prevent you from having to re-run the entire build when only the deployment fails.
68
68
69
69
2. As a best practice, add lines for `workflows:`, `version: 2` and `<workflow_name>` at the *end* of the master `.circle/config.yml` file, replacing `<workflow_name>` with a unique name for your workflow. **Note:** The Workflows section of the `config.yml` file is not nested in the config. It is best to put the Workflows at the end of the file because the Workflows `version: 2` is in addition to the `version:` key at the top of the `config.yml` file.
This document describes the Workflows feature and provides details and examples in the following sections:
10
+
To increase the speed of your software development through faster feedback, shorter reruns, and more efficient use of resources, configure Workflows. For example, if only one job in your Workflow fails, you will know it is failing in real-time and you can rerun *just the failed job* instead of wasting time and resources waiting for the entire build to fail or rerunning the entire set of jobs. This document describes the Workflows feature and provides example configurations in the following sections:
11
11
12
12
* TOC
13
13
{:toc}
14
-
15
-
16
-
To enable Workflows, you must first split the single job in your CircleCI 2.0 `config.yml` file into multiple jobs with unique names, if you have not already done so. Job names must be unique within a `config.yml` file. See [Migrating from 1.0 to 2.0]({{ site.baseurl }}/2.0/migrating-from-1-2/) for instructions.
17
14
18
15
## Overview
19
16
20
-
A workflow is a set of rules for defining a collection of jobs and their run order. The Workflows feature is designed with a flexible algorithm to support very complex job scheduling and orchestration using a simple set of new configuration keys. Consider configuring Workflows if you need to meet any of the following requirements:
17
+
A workflow is a set of rules for defining a collection of jobs and their run order that shortens the feedback loop. The Workflows feature supports very complex job orchestration using a simple set of new configuration keys with a powerful user interface to help you resolve failures sooner, for example:
21
18
22
-
- Run and troubleshoot jobs independently
23
-
- Fan-out to run multiple jobs in parallel for testing various versions
24
-
- Fan-in for deployment to separate platforms with automated triggers
25
-
- Support branch-level and Git tag job execution
26
-
- Enable manual job approval to control deployments to separate environments
27
-
28
-
For example, you might want to run acceptance tests independently from integration tests and use a manual approval process for deployment. Use workflows to orchestrate parts of your build, increase your ability to respond to failures, and control deployment. Scheduled jobs appear in the Workflows tab of the CircleCI app, so you have an integrated view of the status of every individual workflow as shown in the following screenshot.
19
+
- Run and troubleshoot jobs independently with fast status feedback as each job runs
20
+
- Fan-out to run multiple jobs in parallel for efficient testing of versions
21
+
- Fan-in for deployment to separate platforms with increased speed
Select the Failed workflow to see the status of each job as shown in the next screenshot. Click the Rerun button and select From beginning to restart a failed workflow or select From failed to restart a failed job.
25
+
When you use workflows to orchestrate parts of your build, you increase your ability to respond to failures rapidly. Click the Workflows icon in the app and select a workflow to see the status of each job as shown in the next screenshot. Click the Rerun button and select From failed to restart only the failed job and continue the workflow. Only jobs *after* the failure will run, saving time and resources.
Workflows may be configured to wait for manual approval of a job before continuing by using the `type: approval` key. The `type: approval` key is a special job and type that is **only** added under in your `workflow` key. This enables you to configure a job with `type:approval` in the workflow before a set of parallel jobs that must all wait for manual approval. Jobs run in the order defined until the workflow processes a job with the `type: approval` key followed by a job on which it depends as in the following `config.yml` example:
32
+
33
+
```
34
+
workflows:
35
+
version: 2
36
+
build-test-and-approval-deploy:
37
+
jobs:
38
+
- build
39
+
- test1:
40
+
requires:
41
+
- build
42
+
- test2:
43
+
requires:
44
+
- test1
45
+
- hold:
46
+
type: approval
47
+
requires:
48
+
- test1
49
+
- test2
50
+
- deploy:
51
+
requires:
52
+
- hold
53
+
```
54
+
55
+
In this example, the `deploy:` job will not run until you click the Approve button on the `hold` job in the Workflows page of the CircleCI app. Notice that the `hold` job must have a unique name that is not used by any other job. The workflow will wait with the status of On Hold until you click the button. After you approve the job with `type: approval`, the next job or jobs which require it will start. In this example, the purpose is to wait for approval to begin deployment. To configure this behavior, the `hold` job must be `type: approval` and the `deploy` job must require `hold`.
37
56
38
-
The basic Workflows configuration runs all jobs in parallel. That is, jobs listed in the `workflows` section without additional keys will run at the same time. The blue icons indicate the Running status.
57
+
To run a set of parallel jobs, add a new `workflows:` section to the end of your existing `.circleci/config.yml` file with the version and a unique name for the workflow. The following sample `.circleci/config.yml` file shows the default workflow orchestration with four parallel jobs. It is defined by using the `workflows:` key named `build_and_test` and by nesting the `jobs:` key with a list of job names. The jobs have no dependencies defined, therefore they will run in parallel.
61
+
To run a set of parallel jobs, add a new `workflows:` section to the end of your existing `.circleci/config.yml` file with the version and a unique name for the workflow. The following sample `.circleci/config.yml` file shows the default workflow orchestration with two parallel jobs. It is defined by using the `workflows:` key named `build_and_test` and by nesting the `jobs:` key with a list of job names. The jobs have no dependencies defined, therefore they will run in parallel.
43
62
44
63
```yaml
45
64
version: 2
46
65
jobs:
47
66
build:
48
-
docker:
49
-
- image: circleci/<language>:<version TAG>
50
-
steps:
51
-
- checkout
52
-
test1:
53
67
docker:
54
68
- image: circleci/<language>:<version TAG>
55
69
steps:
56
70
- checkout
57
71
- run: <command>
58
-
test2:
59
-
docker:
60
-
- image: circleci/<language>:<version TAG>
61
-
steps:
62
-
- checkout
63
-
- run: <command>
64
-
test3:
72
+
test:
65
73
docker:
66
74
- image: circleci/<language>:<version TAG>
67
75
steps:
@@ -72,13 +80,11 @@ workflows:
72
80
build_and_test:
73
81
jobs:
74
82
- build
75
-
- test1
76
-
- test2
77
-
- test3
83
+
- test
78
84
```
79
85
See the [Sample Parallel Workflow config](https://github.com/CircleCI-Public/circleci-demo-workflows/blob/parallel-jobs/.circleci/config.yml) for a full example.
80
86
81
-
## Sequential Job Execution Example
87
+
### Sequential Job Execution Example
82
88
83
89
The following example shows a workflow with four sequential jobs. The jobs run according to configured requirements, each job waiting to start until the required job finishes successfully as illustrated in the diagram.
84
90
@@ -107,79 +113,7 @@ The dependencies are defined by setting the `requires:` key as shown. The `deplo
107
113
108
114
See the [Sample Sequential Workflow config](https://github.com/CircleCI-Public/circleci-demo-workflows/blob/sequential-branch-filter/.circleci/config.yml) for a full example.
109
115
110
-
## Job Contexts Example
111
-
112
-
The following example shows a workflow with four sequential jobs that use shared environment variables.
113
-
114
-
The following `config.yml` snippet is an example of a sequntial job workflow configured to use the resources defined in the `org-global` context:
115
-
116
-
```
117
-
workflows:
118
-
version: 2
119
-
build-test-and-deploy:
120
-
jobs:
121
-
- build
122
-
- test1:
123
-
requires:
124
-
- build
125
-
context: org-global
126
-
- test2:
127
-
requires:
128
-
- test1
129
-
context: org-global
130
-
- deploy:
131
-
requires:
132
-
- test2
133
-
```
134
-
135
-
The environment variables are defined by setting the `context` key as shown to the default name `org-global`. The `test1` and `test2` jobs in this workflows example will use the same shared environment variables when initiated by a user who is part of the organization. By default, all projects in an organization have access to contexts set for that organization.
136
-
137
-
See the [Contexts]({{ site.baseurl }}/2.0/contexts) document for detailed instructions on this setting in the application.
138
-
139
-
140
-
## Holding a Workflow for a Manual Approval
141
-
142
-
Workflows may be configured to wait for manual approval of a job before continuing by using the `type: approval` key. The `type: approval` key is a special job and type that is **only** added under in your `workflow` key. This enables you to configure a job with `type:approval` in the workflow before a set of parallel jobs that must all wait for manual approval. Jobs run in the order defined until the workflow processes a job with the `type: approval` key followed by a job on which it depends as in the following `config.yml` example:
143
-
144
-
```
145
-
workflows:
146
-
version: 2
147
-
build-test-and-approval-deploy:
148
-
jobs:
149
-
- build
150
-
- test1:
151
-
requires:
152
-
- build
153
-
- test2:
154
-
requires:
155
-
- test1
156
-
- hold:
157
-
type: approval
158
-
requires:
159
-
- test1
160
-
- test2
161
-
- deploy:
162
-
requires:
163
-
- hold
164
-
```
165
-
166
-
In this example, the `deploy:` job will not run until you click the Approve button on the `hold` job in the Workflows page of the CircleCI app. Notice that the `hold` job must have a unique name that is not used by any other job. The workflow will wait with the status of On Hold until you click the button. After you approve the job with `type: approval`, the next job or jobs which require it will start. In this example, the purpose is to wait for approval to begin deployment. To configure this behavior, the `hold` job must be `type: approval` and the `deploy` job must require `hold`.
167
-
168
-
169
-
170
-
## Running a Workflow from a Failed Job
171
-
172
-
It is possible to rerun a job that failed in the middle of a workflow and continue the rest of the workflow using the Rerun button on the Workflows page of the CircleCI application.
173
-
174
-
175
-
176
-
To rerun a workflow from the failed job:
177
-
178
-
1. Click the Workflows icon and select a project to display workflows.
179
-
2. Select a workflow from the list to see all jobs in the workflow.
180
-
3. Click Rerun and select from failed to rerun the job and continue the workflow.
181
-
182
-
## Fan-Out/Fan-In Workflow Example
116
+
### Fan-Out/Fan-In Workflow Example
183
117
184
118
The illustrated example workflow runs a common build Job, then fans-out to run a set of acceptance test Jobs in parallel, and finally fans-in to run a common deploy Job.
185
119
@@ -216,7 +150,40 @@ In this example, as soon as the `build` job finishes successfully, all four acce
216
150
217
151
See the [Sample Fan-in/Fan-out Workflow config](https://github.com/CircleCI-Public/circleci-demo-workflows/tree/fan-in-fan-out) for a full example.
218
152
219
-
## Branch-Level Job Execution
153
+
## Using Contexts and Filtering in Your Workflows
154
+
155
+
The following sections provide example for using Contexts and filters to manage job execution.
156
+
157
+
### Using Job Contexts to Share Environment Variables
158
+
159
+
The following example shows a workflow with four sequential jobs that use shared environment variables.
160
+
161
+
The following `config.yml` snippet is an example of a sequntial job workflow configured to use the resources defined in the `org-global` context:
162
+
163
+
```
164
+
workflows:
165
+
version: 2
166
+
build-test-and-deploy:
167
+
jobs:
168
+
- build
169
+
- test1:
170
+
requires:
171
+
- build
172
+
context: org-global
173
+
- test2:
174
+
requires:
175
+
- test1
176
+
context: org-global
177
+
- deploy:
178
+
requires:
179
+
- test2
180
+
```
181
+
182
+
The environment variables are defined by setting the `context` key as shown to the default name `org-global`. The `test1` and `test2` jobs in this workflows example will use the same shared environment variables when initiated by a user who is part of the organization. By default, all projects in an organization have access to contexts set for that organization.
183
+
184
+
See the [Contexts]({{ site.baseurl }}/2.0/contexts) document for detailed instructions on this setting in the application.
185
+
186
+
### Branch-Level Job Execution
220
187
The following example shows a workflow configured with jobs on three branches: Dev, Stage, and Pre-Prod. Workflows will ignore `branches` keys nested under `jobs` configuration, so if you use job-level branching and later add workflows, you must remove the branching at the job level and instead declare it in the workflows section of your `config.yml`, as follows:
In the example, `filters` is set with the `branches` key and the `only` key with the branch name. Any branches that match the value of `only` will run the job. Branches matching the value of `ignore` will not run the job. See the [Sample Sequential Workflow config with Branching](https://github.com/CircleCI-Public/circleci-demo-workflows/blob/sequential-branch-filter/.circleci/config.yml) for a full example.
248
215
249
-
## Git Tag Job Execution
216
+
###Git Tag Job Execution
250
217
251
218
CircleCI treats tag and branch filters differently when deciding whether a job should run.
0 commit comments