diff --git a/docs/guides/modules/ROOT/images/artifacts.png b/docs/guides/modules/ROOT/images/artifacts.png index c786e890cc..bd607aa04b 100644 Binary files a/docs/guides/modules/ROOT/images/artifacts.png and b/docs/guides/modules/ROOT/images/artifacts.png differ diff --git a/docs/guides/modules/ROOT/images/config-approval-complete.png b/docs/guides/modules/ROOT/images/config-approval-complete.png index 53a59383ae..41be99c30b 100644 Binary files a/docs/guides/modules/ROOT/images/config-approval-complete.png and b/docs/guides/modules/ROOT/images/config-approval-complete.png differ diff --git a/docs/guides/modules/ROOT/images/config-first-step.png b/docs/guides/modules/ROOT/images/config-first-step.png index f8c57034ef..bbb91e2c2b 100644 Binary files a/docs/guides/modules/ROOT/images/config-first-step.png and b/docs/guides/modules/ROOT/images/config-first-step.png differ diff --git a/docs/guides/modules/ROOT/images/config-intro-part1-job.png b/docs/guides/modules/ROOT/images/config-intro-part1-job.png index 7b13b69f06..bfd7baec56 100644 Binary files a/docs/guides/modules/ROOT/images/config-intro-part1-job.png and b/docs/guides/modules/ROOT/images/config-intro-part1-job.png differ diff --git a/docs/guides/modules/ROOT/images/config-intro-part3.png b/docs/guides/modules/ROOT/images/config-intro-part3.png index 473c8d9f6f..9130924741 100644 Binary files a/docs/guides/modules/ROOT/images/config-intro-part3.png and b/docs/guides/modules/ROOT/images/config-intro-part3.png differ diff --git a/docs/guides/modules/ROOT/images/config-node-job.png b/docs/guides/modules/ROOT/images/config-node-job.png index 5dd8e2b93d..c83009c1bb 100644 Binary files a/docs/guides/modules/ROOT/images/config-node-job.png and b/docs/guides/modules/ROOT/images/config-node-job.png differ diff --git a/docs/guides/modules/ROOT/images/config-on-hold.png b/docs/guides/modules/ROOT/images/config-on-hold.png index 81b4efbf8b..2e24e70577 100644 Binary files a/docs/guides/modules/ROOT/images/config-on-hold.png and b/docs/guides/modules/ROOT/images/config-on-hold.png differ diff --git a/docs/guides/modules/ROOT/images/config-second-step.png b/docs/guides/modules/ROOT/images/config-second-step.png index ff80cac469..6b2469cf34 100644 Binary files a/docs/guides/modules/ROOT/images/config-second-step.png and b/docs/guides/modules/ROOT/images/config-second-step.png differ diff --git a/docs/guides/modules/getting-started/pages/config-intro.adoc b/docs/guides/modules/getting-started/pages/config-intro.adoc index f80fadd3ec..c458d8b556 100644 --- a/docs/guides/modules/getting-started/pages/config-intro.adoc +++ b/docs/guides/modules/getting-started/pages/config-intro.adoc @@ -18,14 +18,19 @@ This guide covers the following topics: * How to use workflows to orchestrate your build. * How to add approval steps to your workflow. -CircleCI believes in *configuration as code*. Consequently, the entire delivery 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 top of your repository project. CircleCI uses the YAML syntax for config. See the xref:introduction-to-yaml-configurations.adoc[Introduction to YAML configurations] page for guidance on the basics. +CircleCI believes in *configuration as code*. The entire delivery process from build to deploy is orchestrated through YAML configuration files. A common pattern is to name your configuration file `config.yml` and store it in a folder called `.circleci` at the top of your repository project. See the xref:introduction-to-yaml-configurations.adoc[Introduction to YAML Configurations] page for guidance on the basics. + +== Prerequisites + +* A CircleCI account. You can link:https://circleci.com/signup/[sign up for free]. +* A code repository you want to build on CircleCI. +* Follow the xref:create-project.adoc[Create a Project] guide to connect your repository to CircleCI. You can then use the examples below to configure a basic pipeline using any execution environment. [#part-1-using-the-shell] == Part 1: Using the shell CircleCI provides an on-demand shell to run commands. In this first example, you will set up a build and execute a shell command. -. If you have not done so already, <> and then either create or set up a new project. You can follow the steps to connect a code repository in our xref:getting-started.adoc[Quickstart guide]. . Once you have created or set up your project in CircleCI, go to the `.circleci/config.yml` file and replace its contents with the following code: + include::ROOT:partial$notes/docker-auth.adoc[] @@ -66,10 +71,12 @@ As mentioned in the note above the sample code, you may optionally supply your D . A new pipeline is triggered in CircleCI. You can see the output in the link:https://app.circleci.com/[CircleCI dashboard]. A green tick denotes a successful pipeline. A red exclamation mark alerts you to a failure. Click on the job for more details. + +.Successful build job image::guides:ROOT:config-intro-part1-job.png[Successful build job] + You should see your step - The First Step - with the output of the commands: + +.Successful step within job image::guides:ROOT:config-first-step.png[Successful step within job] NOTE: Although the `config.yml` syntax itself is straightforward, the indentation is more complicated. Incorrect indentation is the most common error. If you are experiencing problems with this example, check your indentation carefully, or copy and paste the sample code. @@ -123,6 +130,7 @@ You should now see some additional steps on the CircleCI dashboard: * *Checkout code* has cloned the code from your git repository. * *The Second Step* has listed the files found in your git repository. +.Successful step within job list files in repository image::guides:ROOT:config-second-step.png[Checking out your repository] [#part-3-using-different-environments-and-creating-workflows] @@ -143,7 +151,7 @@ jobs: # running commands on a basic image Hello-World: docker: - - image: cimg/base:2021.04 + - image: cimg/base:2026.03 steps: - run: name: Saying Hello @@ -153,7 +161,7 @@ jobs: # fetching code from the repo Fetch-Code: docker: - - image: cimg/base:2021.04 + - image: cimg/base:2026.03 steps: - checkout - run: @@ -164,7 +172,7 @@ jobs: # running a node container Using-Node: docker: - - image: cimg/node:17.2 + - image: cimg/node:25.8.1 steps: - run: name: Running the Node Container @@ -192,7 +200,7 @@ The following commentary describes what occurs in each line of the sample code: * *Lines 15-16:* The _Fetch-Code_ job uses a basic git-compatible image. * *Lines 17-23:* This code is repeated from Part 2, but now it is a separate job. * *Line 25:* The third job is _Using-Node_. -* *Lines 26-27:* This _Using-Node_ job uses a Docker image called `cimg/node:17.2`. This image contains version 17.2 of Node, along with a browser and other useful tools. +* *Lines 26-27:* This _Using-Node_ job uses a Docker image called `cimg/node:25.8.1`. This image contains version 25.8.1 of Node, along with a browser and other useful tools. * *Lines 28-32:* As in the previous jobs, there is a _run_ step. This time, the command `node -v` prints the version of Node running in the container. * *Lines 33-34:* This line creates a workflow called _Example-Workflow_. Workflows define a list of jobs and their run order. * *Lines 35-36:* These lines specify the first job, _Hello-World_. @@ -203,10 +211,12 @@ As before, commit and push your updated `config.yml` file. In CircleCI, your pipeline will look different. Your workflow is now called _Example-Workflow_ and you have three jobs, rather than just one. +.Running multiple jobs image::guides:ROOT:config-intro-part3.png[Running multiple jobs] If you click on the _Using-Node_ job and then the _Running the Node Container_ step, you should see that the command `node -v` has printed the version of Node. +.Running Node job image::guides:ROOT:config-node-job.png[Running Node job] In this example, you have: @@ -216,7 +226,7 @@ In this example, you have: * Created a workflow to define the order in which your jobs run. * Introduced some logic to ensure that the previous job must complete successfully before the next job is executed. -TIP: To increase your understanding, experiment with other xref:execution-managed:circleci-images.adoc[CircleCI images], or add some more jobs to your workflow. +TIP: To increase your understanding, experiment with other xref:execution-managed:circleci-images.adoc[CircleCI Images], or add some more jobs to your workflow. [#part-4-adding-a-manual-approval] == Part 4: Adding a manual approval @@ -236,7 +246,7 @@ jobs: # running commands on a basic image Hello-World: docker: - - image: alpine:3.15 + - image: alpine:3.23.3 steps: - run: name: Saying Hello @@ -246,7 +256,7 @@ jobs: # fetching code from the repo Fetch-Code: docker: - - image: cimg/base:2021.04 + - image: cimg/base:2026.03 steps: - checkout - run: @@ -257,7 +267,7 @@ jobs: # running a node container Using-Node: docker: - - image: cimg/node:17.2 + - image: cimg/node:25.8.1 steps: - run: name: Running the Node Container @@ -265,7 +275,7 @@ jobs: node -v Now-Complete: docker: - - image: alpine:3.15 + - image: alpine:3.23.3 steps: - run: name: Approval Complete @@ -292,7 +302,7 @@ workflows: - Hold-for-Approval ---- -Most of this code will look familiar to you. There are a couple of important additions: +Most of this code will look familiar to you, with a couple of important points: * *Lines 52-56*: This creates a new job called _Hold-for-Approval_. The `type` specifies this is an _approval_, so you are required to manually approve this job in CircleCI. This is useful if you want to see whether the previous jobs have been executed as expected. For example, you can check that a website looks correct on a test server before making it live. Or you might want a human to perform checks before you execute any expensive jobs. * *Lines 57-59*: This final job - _Now-Complete_ - `requires` the successful completion of _Hold-for-Approval_, so will execute only once you have approved that previous job in CircleCI. @@ -301,6 +311,7 @@ As before, commit and push your updated `config.yml` file. If you look at your pipeline in CircleCI, you will see the a purple status badge of *Needs Approval*. +.Job requires approval image::guides:ROOT:config-on-hold.png[Job requires approval] To approve the job, click the thumbs up icon to the right of the _Hold-for-Approval_ job in the _Actions_ column. In the pop-up message, click the blue btn:[Approve] button. @@ -309,6 +320,7 @@ Now you will see a tick in the Actions column and your jobs should complete. Select the _Now-Complete_ job, then the _Approval Complete_ step. You should see the output of your command: `The work is now complete`. +.Approval complete image::guides:ROOT:config-approval-complete.png[Approval complete] TIP: If you encounter errors, the problem is likely to be caused by incorrect indentation. The xref:config-editor.adoc[CircleCI Configuration Editor] validates your syntax, provides autocomplete suggestions, and offers tips. @@ -323,10 +335,11 @@ Using what you have learned above, you are ready to create some powerful pipelin [#visual-studio-code-extension] ## VS Code extension -If you use VS Code, you might find the official xref:toolkit:vs-code-extension-overview.adoc[CircleCI extension] useful when writing, editing, navigating and troubleshooting your YAML Config files. +If you use VS Code, you might find the official xref:toolkit:vs-code-extension-overview.adoc[CircleCI Extension] useful when writing, editing, navigating and troubleshooting your YAML Config files. The extension provides real-time syntax highlighting and validation, assisted navigation through go-to-definition and go-to-reference commands, usage hints, and autocomplete suggestions. +.Screenshot showing the definition available on hover image::guides:ROOT:vs_code_extension_config_helper_go-to-definition-optimised.gif[Screenshot showing the definition available on hover] The CircleCI VS Code extension is available to download on the link:https://marketplace.visualstudio.com/items?itemName=circleci.circleci[VS Code marketplace.]