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
CircleCI believes in *configuration as code*. Your entire continuous integration and deployment process is orchestrated through a single file called `config.yml`. The `config.yml` file is located in a folder called `.circleci` at the root of your project. CircleCI uses the YAML syntax for config, see the [Writing YAML]({{ site.baseurl }}/2.0/writing-yaml/) document for basics.
29
+
30
+
```bash
31
+
├── .circleci
32
+
│ ├── config.yml
33
+
├── README
34
+
└── all-other-project-files-and-folders
35
+
```
36
+
37
+
`config.yml` is a powerful YAML file that defines the entire pipeline for your project. For a full overview of the various keys that are used, see the [Configuration Reference]({{ site.baseurl }}/2.0/configuration-reference/).
31
38
39
+
Your CircleCI configuration can be adapted to fit many different needs of your project. The following terms, sorted in order of granularity and dependence, describe the components of most common CircleCI projects:
40
+
41
+
-**[Pipeline](#pipelines)**: Represents the entirety of your configuration.
42
+
-**[Workflows](#workflows)**: Responsible for orchestrating multiple _jobs_.
43
+
-**[Jobs](#jobs)**: Responsible for running a series of _steps_ that perform commands.
44
+
-**[Steps](#steps)**: Run commands (such as installing dependencies or running tests) and shell scripts to do the work required for your project.
45
+
46
+
The following image uses an [example Java application](https://github.com/CircleCI-Public/circleci-demo-java-spring/tree/2.1-config) to show the various config elements:
It is worth taking a minute to define the various user types that relate to CircleCI projects, most of which have permissions inherited from VCS accounts.
33
53
34
54
* The *Organization Administrator* is a permission level inherited from your VCS:
@@ -42,53 +62,30 @@ username and password. Users must be added to a [GitHub or Bitbucket org]({{
42
62
site.baseurl }}/2.0/gh-bb-integration/) to view or follow associated CircleCI
43
63
projects. Users may not view project data that is stored in environment variables.
44
64
65
+
45
66
## Pipelines
46
67
47
-
A CircleCI pipeline is the full set of processes you run when you trigger work on your projects. Pipelines encompass your workflows, which in turn coordinate your jobs. This is all defined in your project [configuration file](#config).
68
+
A CircleCI pipeline is the full set of processes you run when you trigger work on your projects. Pipelines encompass your workflows, which in turn coordinate your jobs. This is all defined in your project [configuration file](#configuration).
48
69
49
-
Pipelines offer the following benefits:
70
+
Pipelines represent methods for interacting with your configuration:
50
71
51
72
{% include snippets/pipelines-benefits.adoc %}
52
73
53
74
## Orbs
54
-
Orbs are reusable snippets of code that help automate repeated processes, speed up project setup, and make it easy to integrate with third-party tools. See [Using Orbs]({{ site.baseurl }}/2.0/using-orbs/) for details about how to use orbs in your config and an introduction to orb design. Visit the [Orbs Registry](https://circleci.com/orbs/registry/) to search for orbs to help simplify your config.
55
-
56
-
## Config
57
75
58
-
CircleCI believes in *configuration as code*. The entire pipeline process, from build to deploy, is orchestrated through a single file called `config.yml`. The `config.yml` file is located in a folder called `.circleci` at the root of your project. CircleCI uses the YAML syntax for config, see the [Writing YAML]({{ site.baseurl }}/2.0/writing-yaml/) document for basics.
59
-
60
-
```sh
61
-
├── .circleci
62
-
│ ├── config.yml
63
-
├── README
64
-
└── all-your-projects-other-files-and-folders
65
-
```
66
-
67
-
`config.yml` is a powerful yaml file that defines the entire pipeline for your project. For a full overview of the various keys that can be used see the [Configuration Reference]({{ site.baseurl }}/2.0/configuration-reference/).
68
-
69
-
Put very simply:
70
-
71
-
* You will define [workflows](#workflows) that orchestrate a series of [jobs](#jobs).
72
-
* Each job will contain a number of [steps](#steps) to run commands and shell scripts to do the work required for your project.
73
-
* Each job runs in an independent [executor](#executors-and-images) (container or virtual machine).
74
-
*[Caches](#caches-workspaces-and-artifacts) are available to optimize and speed up pipelines.
75
-
*[Workspaces/artifacts](#caches-workspaces-and-artifacts) can be used to share data across your pipeline.
76
-
77
-
The following image uses an [example Java application](https://github.com/CircleCI-Public/circleci-demo-java-spring/tree/2.1-config) to show the various config elements (**Note:** The `test` job used in the example repo has been removed here to keep the image a reasonable size):
Orbs are reusable snippets of code that help automate repeated processes, speed up project setup, and make it easy to integrate with third-party tools. See [Using Orbs]({{ site.baseurl }}/2.0/using-orbs/) for details about how to use orbs in your config and an introduction to orb design. Visit the [Orbs Registry](https://circleci.com/orbs/registry/) to search for orbs to help simplify your config.
80
77
81
-
And now the [same example using the Maven orb](https://github.com/CircleCI-Public/circleci-demo-java-spring/tree/2.1-orbs-config) illustrates how orbs can be used to simplify your project configuration:
78
+
The graphic above illustrating an example Java configuration can be greatly simplified using orbs. The following illustration re-creates the same configuration with [the Maven orb](https://github.com/CircleCI-Public/circleci-demo-java-spring/tree/2.1-orbs-config).
82
79
83
80
84
81
85
-
###Jobs
82
+
## Jobs
86
83
87
84
Jobs are the building blocks of your config. Jobs are collections of [steps](#steps), which run commands/scripts as required. Each job must declare an executor that is either `docker`, `machine`, `windows` or `macos`. `machine` includes a [default image](https://circleci.com/docs/2.0/executor-intro/#machine) if not specified, for `docker` you must [specify an image](https://circleci.com/docs/2.0/executor-intro/#docker) to use for the primary container, for `macos` you must specify an [Xcode version](https://circleci.com/docs/2.0/executor-intro/#macos), and for `windows` you must use the [Windows orb](https://circleci.com/docs/2.0/executor-intro/#windows).
Each separate job defined within your config will run in a unique executor. An executor can be a docker container or a virtual machine running Linux, Windows, or MacOS. Note, macOS is not currently available on self-hosted installations of CircleCI Server.
94
91
@@ -162,7 +159,7 @@ The Primary Container is defined by the first image listed in [`.circleci/config
162
159
163
160
When using the docker executor and running docker commands, the `setup_remote_docker` key can be used to spin up another docker container in which to run these commands, for added security. For more information see the [Running Docker Commands]({{ site.baseurl }}/2.0/building-docker-images/#accessing-the-remote-docker-environment) guide.
164
161
165
-
####Steps
162
+
## Steps
166
163
167
164
Steps are actions that need to be taken to complete your job. Steps are usually a collection of executable commands. For example, the [`checkout`]({{ site.baseurl }}/2.0/configuration-reference/#checkout) step, which is a _built-in_ step available across all CircleCI projects, checks out the source code for a job over SSH. Then, the `run` step allows you to run custom commands, such as executing the command `make test` using a non-login shell by default. Commands can also be defined [outside the job declaration]({{ site.baseurl }}/2.0/configuration-reference/#commands-requires-version-21), making them reusable across your config.
168
165
@@ -183,7 +180,7 @@ jobs:
183
180
#...
184
181
```
185
182
186
-
###Workflows
183
+
## Workflows
187
184
188
185
Workflows define a list of jobs and their run order. It is possible to run jobs concurrently, sequentially, on a schedule, or with a manual gate using an approval job.
0 commit comments