Skip to content

Commit 41e5db0

Browse files
michelle-lunamichelle-luna
authored
create new document
1 parent 6f9c1f9 commit 41e5db0

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎jekyll/_cci2/workflows.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
layout: classic-docs
3+
title: "Orchestrating Workflows"
4+
short-title: "Orchestrating Workflows"
5+
description: "Orchestrating Workflows"
6+
categories: [configuring-jobs]
7+
order: 30
8+
---
9+
10+
This section describes the Workflows feature and provides examples for parallel, sequential, fan-in, fan-out, and branch-level workflows. To enable Workflows, you must first split the single job in your `config.yml` file into multiple jobs, if you have not already done so. Job names must be unique within a `config.yml` file.
11+
 
12+
## Overview
13+
14+
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:
15+
 
16+
- Run and troubleshoot jobs independently
17+
- Fan-out to run multiple jobs in parallel for testing various versions  
18+
- Fan-in for deployment to separate platforms with automated triggers
19+
- Branch-level job execution with artifact sharing
20+
21+
For example, you might want to run acceptance tests independently from integration tests and deployment. Use workflows to orchestrate parts of your build and to increase your ability to respond to failures. 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.
22+
23+
![CircleCI Workflows Page]({{ site.baseurl }}/assets/img/docs/workflow_landing.png)
24+
25+
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.
26+
27+
![CircleCI Workflows Page]({{ site.baseurl }}/assets/img/docs/workflow_detail.png)
28+
29+
## Parallel Job Execution Example
30+
31+
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.
32+
33+
![Parallel Job Execution Workflow]({{ site.baseurl }}/assets/img/docs/parallel_jobs.png) 
34+
35+
To run a set of parallel jobs, add a new `workflows:` section to the end of your existing configuration file with the version and a unique name for the workflow. The following `.circleci/config.yml` file snippet shows an example workflow 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.
36+
37+
```
38+
workflows:
39+
version: 2
40+
build-and-test:
41+
jobs:
42+
- build
43+
- test1
44+
- test2
45+
- test3
46+
```
47+
48+
## Sequential Job Execution Example
49+
50+
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.
51+
52+
![Sequential Job Execution Workflow]({{ site.baseurl }}/assets/img/docs/sequntial_workflow.png)
53+
54+
The following `config.yml` snippet is an example of a workflow configured for sequential job execution:
55+
56+
```
57+
workflows:
58+
 version: 2
59+
 build-test-and-deploy:
60+
   jobs:
61+
     - build
62+
     - test1:
63+
         requires:
64+
           - build
65+
     - test2:
66+
         requires:
67+
           - test1
68+
     - deploy:
69+
         requires:
70+
           - test2
71+
```
72+
73+
The dependencies are defined by setting the `requires:` key as shown. The `deploy:` job will not run until the `build` and `test` jobs complete successfully. A job must wait until all upstream jobs in the dependency graph have run. So, the `deploy` job waits for the `test2` job, the `test2` job waits for the `test1` job and the `test1` job waits for the `build` job.
74+
 
75+
The Workflows feature also enables you to limit the job execution to a branch with the `filters` key. See the Branch-Level Job Execution section for instructions.
76+
 
77+
## Running a Workflow from a Failed Job
78+
79+
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.
80+
81+
![Rerunning a Workflow from a Failed Job]({{ site.baseurl }}/assets/img/docs/restart_from_failed.png) 
82+
83+
To rerun a workflow from the failed job:
84+
85+
1. From the Builds page, select the project name.

86+
2. Click the Workflows tab to display workflows for your project. 

87+
3. Select a workflow from the list to see all jobs in the workflow.

88+
4. Click Rerun and select from failed to rerun the job and continue the workflow.

89+
90+
## Fan-Out/Fan-In Workflow Example
91+
92+
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.
93+
94+
![Fan-out and Fan-in Workflow]({{ site.baseurl }}/assets/img/docs/fan_in_out.png) 
95+
96+
The following `config.yml` snippet is an example of a workflow configured for sequential job execution:
97+
98+
``` 
99+
workflows:
100+
 version: 2
101+
 build_accept_deploy:
102+
   jobs:
103+
     - build:
104+
     - acceptance_test_1:
105+
         requires:
106+
           - build
107+
     - acceptance_test_2:
108+
         requires:
109+
           - build
110+
     - acceptance_test_3:
111+
         requires:
112+
           - build
113+
     - acceptance_test_4:
114+
         requires:
115+
           - build          
116+
     - deploy:
117+
         requires:
118+
           - acceptance_test_1
119+
           - acceptance_test_2
120+
           - acceptance_test_3
121+
           - acceptance_test_4
122+
```
123+
 
124+
## Branch-Level Job Execution
125+
The following example shows a workflow configured with jobs on three branches: Dev, Stage, and Pre-Prod.
126+
127+
![Branch-Level Job Execution]({{ site.baseurl }}/assets/img/docs/branch_level.png) 
128+
129+
The following `config.yml` snippet is an example of a workflow configured for branch-level job execution:
130+
131+
```
132+
workflows:
133+
 version:2
134+
 dev_stage_pre-prod_master_deploy:
135+
   jobs:
136+
     - test_dev:
137+
         filters:
138+
           branches:
139+
             only: dev
140+
     - test_stage:
141+
         filters:
142+
           branches:
143+
             only: stage
144+
     - test_pre-prod:
145+
         filters:
146+
           branches:
147+
             only: pre-prod
148+
```
149+
150+
## Workspaces
151+
152+
Workflows that include jobs running on multiple branches may require artifacts to be shared using workspaces. To persist an artifact from a job and make it available to other jobs, configure the job to use the `persist_to_workspace` key where the value is a directory inside the project’s working directory. Artifacts of the job will be saved to this directory until the job is rerun and new artifacts are created.
153+
154+
Configure a job to get a saved artifact by configuring the `attach_workspace` key where the value of the `at:` option is the directory defined in the `persist_to_workspace` key. The following `config.yml` file defines two jobs where the `downstream` job uses the artifact of the `flow` job. The workflow configuration is sequential, so that `downstream` requires `flow` to finish before it can start.
155+
 
156+
```
157+
defaults: &defaults
158+
 working_directory: /tmp
159+
 docker:
160+
   - image: buildpack-deps:jessie
161+
162+
version: 2
163+
jobs:
164+
 flow:
165+
   <<: *defaults
166+
   steps:
167+
     - run: mkdir -p workspace
168+
     - run: echo "Hello, world!" > workspace/echo-output
169+
170+
     - persist_to_workspace:
171+
         root: workspace
172+
         paths:
173+
           - echo-output
174+
175+
 downstream:
176+
   <<: *defaults
177+
   steps:
178+
     - attach_workspace:
179+
         at: /tmp/workspace
180+
181+
     - run: |
182+
         if [[ `cat workspace/echo-output` == "Hello, world!" ]]; then
183+
           echo "It worked!";
184+
         else
185+
           echo "Nope!"; exit 1
186+
         fi
187+
188+
workflows:
189+
 version: 2
190+
191+
 btd:
192+
   jobs:
193+
     - flow
194+
     - downstream:
195+
         requires:
196+
           - flow
197+
```
198+
199+
## See Also
200+
201+
- For procedural instructions on how to add Workflows your configuration as you are migrating from a 1.0 `circle.yml` file to a 2.0 `.circelci/config.yml` file, see the [Steps to Configure Workflows]({{ site.baseurl }}/2.0/migrating-1-2/) section of the Migrating from 1.0 to 2.0 document.
202+
203+
- For details about the `workflows:` key requirements, see the [Workflows]({{ site.baseurl }}/2.0/configuration-reference/#workflows) section of the Writing Jobs with Steps document.
204+
205+
- For frequently asked questions and answers about Workflows, see the [Workflows]({{ site.baseurl }}/2.0/faq) section of the Migration FAQ.

0 commit comments

Comments
 (0)