diff --git a/jekyll/_cci2/getting-started.adoc b/jekyll/_cci2/getting-started.adoc index 4ff05cd679f..6ade78d5324 100644 --- a/jekyll/_cci2/getting-started.adoc +++ b/jekyll/_cci2/getting-started.adoc @@ -9,13 +9,18 @@ contentTags: :page-description: A quickstart guide for adding a project to CircleCI and exploring some features :page-liquid: -This quickstart guide takes you through connecting an existing project to CircleCI, using the in-app config editor, and inviting team members to collaborate on your new project. +This quickstart provides a guided tour through setting up a project, collaborating, and tools to iterate on and debug your build configuration. The following sections cover the following: + +* Create a project, connecting some existing code to CircleCI. +* Inviting team members to collaborate on your new project. +* Use the VS Code extention to debug and extend your config. +* SSH into a build to debug your project. If you would rather jump to a full list of CircleCI `config.yml` options, see the xref:configuration-reference#[Configuration reference]. == Prerequisites -* A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free]. +* A CircleCI account. You can link:https://circleci.com/signup/[sign up for free]. * A code repository you want to build on CircleCI. pass:[] @@ -24,7 +29,7 @@ pass:[] {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/quick-start--first-step.svg {%- endcapture -%} -{% capture content %} Connect your new code repository, commit a CircleCI configuration file to a new branch, view the pipeline, and see it pass. {% endcapture %} +{% capture content %} Create a project, connect your new code repository, and commit a CircleCI configuration file. View your project build in the CircleCI app. {% endcapture %} {% include getting-started-section-header.html title="1. Connect your code" content=content imagePath=header-banner-1 %} @@ -48,52 +53,55 @@ include::../_includes/partials/tips/check-github-type.adoc[Check your GitHub int [.tab.quickstart1.GitHub_App] -- ++++ -{% capture content %} -In the CircleCI web app, select Projects from the sidebar. Click Create Project, then select the repository you would like to connect from the dropdown. -Don’t see these options? Use the org selector in the top left corner to find the correct organization. -{% endcapture %} - -{%- capture select-project -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/create-project.png -{%- endcapture -%} - -{% include two-up.html title="1. Create a project" content=content imageURL=select-project imageAlt="Select Projects" %} - - -{% capture content %} -Give your project a name, check the options, then click Create Project. A config.yml file is generated for you based on the languages and frameworks used in your project. -{% endcapture %} - -{%- capture configure-your-project -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/generating-config.png -{%- endcapture -%} - -{% include two-up.html title="2. Generate config" content=content imageURL=configure-your-project imageAlt="Config Editor" %} - - -{% capture content %} -Click Commit and Run. This will create a .circleci/config.yml file at the root of your repository on a new branch called circleci-project-setup. At this point you can also choose Review configuration file if you would rather check or make changes to the config file before committing. -{% endcapture %} - -{%- capture commit-run-github -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/commit-run-github-app.png -{%- endcapture -%} - -{% include two-up.html title="3. Commit and run your config" content=content imageURL=commit-run-github imageAlt="Commit a config" %} - - -{% capture content %} -You should soon have a passing pipeline. If you are happy with this configuration, merge it into your main branch, or continue to make changes.{% endcapture %} - -{%- capture congrats-first-green-pipeline -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/pass-pipeline-gitlab.png -{%- endcapture -%} - -{% include two-up.html title="4. Congratulations 🎉" content=content imageURL=congrats-first-green-pipeline imageAlt="Passing pipeline" %} +
+
+
1. Create a project
+

In the CircleCI web app select your org, then select Create Project, then follow the instructions in the app. +Don’t see these options? Select the CircleCI logo in the top bar to get back to your user homepage and check you have the correct org selected.

+
+ +
+ Create a project +
+
+ +
+
+
2. Set up a pipeline
+

Follow the in-app instructions to set up your pipelinem including connecting your code, preparing a config file and reviewing triggers. For a more detailed look at this process see the Create a project guide.

+
+ +
+ Follow in-app instructions to set up your pipeline +
+
+ +
+
+
3. Commit and run
+

Once you have gone through the pipeline setup process in the app you have everything you need to commit your config (unless you have a config in your repo already) and build. Review your project details and select Commit config and run. +

+ +
+ Follow in-app instructions to set up your pipeline +
+
+ + +
+
+
4. Congratulations 🎉
+

You should soon have a passing pipeline. In the next sections we will cover ways to modify and debug your config.

+
+ +
+ Follow in-app instructions to set up your pipeline +
+
++++ -- -[.tab.quickstart1.GitLab] +[.tab.quickstart1.GitLab_&_Bitbucket_Data_Center] -- ++++ {% capture content %} @@ -145,62 +153,56 @@ Click Commit and Run. This will create a .circleci/config You should soon have a passing pipeline. If you are happy with this configuration, merge it into your main branch, or continue to make changes.{% endcapture %} {%- capture congrats-first-green-pipeline -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/pass-pipeline-gitlab.png + {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/pass-pipeline.png {%- endcapture -%} {% include two-up.html title="5. Congratulations 🎉" content=content imageURL=congrats-first-green-pipeline imageAlt="Passing pipeline" %} ++++ -- -[.tab.quickstart1.GitHub_OAuth_app_&_Bitbucket] +[.tab.quickstart1.GitHub_OAuth_app_&_Bitbucket_Cloud] -- ++++ -{% capture content %} -In the CircleCI web app, select Projects from the sidebar. Find your repository, and click Set Up Project. -Don’t see your repository? Use the org selector in the top left corner to find the correct organization. -{% endcapture %} - -{%- capture select-project -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/select-project.png -{%- endcapture -%} - -{% include two-up.html title="1. Select a project" content=content imageURL=select-project imageAlt="Select Projects" %} - -{% capture content %} -In the “Select your config.yml file” modal, select Fast, then click Set Up Project. Choose the Hello World sample configuration file. -{% endcapture %} - -{%- capture select-config -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/select-config.png -{%- endcapture -%} - -{% include two-up.html title="2. Select a config.yml" content=content imageURL=select-config imageAlt="Choose Config" %} - -{% capture content %} -You are now in the CircleCI config editor, pre-populated with a sample config.yml file. Click Commit and Run. -
-
-This will create a .circleci/config.yml file at the root of your repository on a new branch called circleci-project-setup. -{% endcapture %} - -{%- capture CCI-config-editor -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/CCI-config-editor-2.png -{%- endcapture -%} - -{% include two-up.html title="3. CircleCI config editor" content=content imageURL=CCI-config-editor imageAlt="Config Editor" %} - -{% capture content %} -You should soon have a passing pipeline. If you are happy with this configuration, merge it into your main branch, or continue to make changes.{% endcapture %} - -{%- capture congrats-first-green-pipeline -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/congrats-first-green-pipeline.png -{%- endcapture -%} - -{% include two-up.html title="4. Congratulations 🎉" content=content imageURL=congrats-first-green-pipeline imageAlt="Green Pipeline Build" %} +
+
+
1. Set up a project
+

In the CircleCI web app select your org, then select Set up a Project, then select Set up Project next to your project in the list. +Don’t see these options? Select the CircleCI logo in the top bar to get back to your user homepage and check you have the correct org selected.

+
+ +
+ Create a project +
+
+ +
+
+
2. Select a config.yml
+

In the “Select your config.yml file” modal, select Faster, then click Set Up Project.

+
+ +
+ Create a project +
+
+ +
+
+
3. Congratulations 🎉
+

You should soon have a passing pipeline. In the next sections we will cover ways to modify and debug your config.

+
+ +
+ Follow in-app instructions to set up your pipeline +
+
++++ -- ++++ + + + {% capture content %} Explore your passing pipeline and invite your teammates to join you, for free. By collaborating, you can troubleshoot, get pull requests approved, and build and test faster. {% endcapture %} {%- capture header-banner-2 -%} @@ -209,86 +211,74 @@ You should soon have a passing pipeline. If you are happy with this configuratio {% include getting-started-section-header.html title="2. Dig into your first pipeline" id="first-pipeline" content=content imagePath=header-banner-2 %} -{% capture content %} -Select the green Success button to see details about a workflow. The workflow expands to show all jobs that ran. -{% endcapture %} - -{%- capture what-just-happened -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/what-just-happened.png -{%- endcapture -%} - -{% include two-up.html title="1. So, what just happened?" content=content imageURL=what-just-happened imageAlt="Green Success Button" %} - - -{% capture content %} -Select a job to enter the job view and see all the steps that ran. -{% endcapture %} - -{%- capture view-results -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/view-results.png -{%- endcapture -%} - -{% include two-up.html title="2. View your results" content=content imageURL=view-results imageAlt="Steps in Pipeline Job" %} - -{% capture content %} -Collaborators can view and follow your projects. Teammates can make a free CircleCI account at any time to view your pipelines, even if they are not committing any code. Invite team members using the Add team members link next to your project name on the dashboard. If you do not see this option, ensure you have a project selected. -{% endcapture %} - -{%- capture collab-with-team -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/collab-with-team.png -{%- endcapture -%} - -{% include two-up.html title="3. Collaborate with teammates" content=content imageURL=collab-with-team imageAlt="Add Team Members" %} - +
+
+
1. So, what just happened?
+

Expand your workflow and select a job to view the steps that ran. Use the tabs along the top to access test results, timing data, artifacts, and resource usage metrics.

+
+ +
+ Exand the workflow and select a job to view steps +
+
+ +
+
+
2. View step output
+

Exand any step to view the build output. You can search, share or download the output for collaboration and debugging. If a step fails, use the Explain this error button for help.

+
+ +
+ Expand a step to view the output. +
+
+ +
+
+
3. Invite teammates
+

Invite teammates to collaborate on your projects. Navigate to Organization Settings > People to generate invites and get further instructions. Collaborators can view and follow your projects. Teammates can make a free CircleCI account at any time to view your pipelines, even if they are not committing any code.

+
+ +
+ Invite teammates to collaborate. Generate invites from your organizaiton settings. +
+
++++ -//// + ++++ -{% capture content %} Break your pipeline to see how errors are surfaced, then explore advanced config options. {% endcapture %} +{% capture content %} Discover CircleCI features to help debug and configure your builds. {% endcapture %} {%- capture header-banner-3 -%} {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/quick-start--third-step.svg {%- endcapture -%} -{% include getting-started-section-header.html title="3. Explore" id="next" content=content imagePath=header-banner-3 %} - -{% capture content %} -Try editing your config.yml file. On CircleCI, you can edit files directly and then commit them to your VCS. On the Projects page, click the ••• buttons to view your configuration file. Make any change and save it. You should see a new pipeline run and likely fail. This is a primary benefit of CircleCI: identifying failures early. -{% endcapture %} - -{%- capture break-your-build -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/break-your-build.png -{%- endcapture -%} - -{% include two-up.html title="1. Break your build" content=content imageURL=break-your-build imageAlt="Failed Job in Pipeline" %} - -{% capture content %} -In your Dashboard, click into the say-hello-world workflow. Can you find the four steps that ran? Hint: step 1 is Spin up environment. -
-
-A workflow is a set of rules that defines a collection of jobs and their run order. Workflows support complex job orchestration using a simple set of configuration keys to help you quickly resolve failures. -{% endcapture %} +{% include getting-started-section-header.html title="3. Debug and iterate" id="next" content=content imagePath=header-banner-3 %} -{%- capture explore-workflows -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/explore-workflows.png -{%- endcapture -%} +
+
+
1. Rerun with SSH
+

To access a job's build environment for troubleshooting, rerun the job with SSH access. The VM remains active for 10 minutes after the pipeline finishes. For full details, see the Debug with SSH page.

+
-{% include two-up.html title="2. Explore the workflows function" content=content imageURL=explore-workflows imageAlt="Explore Your Workflow" %} +
+ Rerun a job with SSH to directly access the build environment. +
+
-{% capture content %} -On a failed pipeline, you can SSH directly into your CircleCI jobs and automatically troubleshoot issues. This feature reruns your pipeline and often finds and fixes errors. -{% endcapture %} +
+
+
2. VS Code extention
+

Using the CircleCI VS Code extention, validate your CircleCI config file. Get help with troubleshooting config updates and help keeping dependencies up to date.

+
-{%- capture SSH-into-build -%} - {{ site.baseurl }}/assets/img/docs/getting-started-guide-exp/SSH-into-build.png -{%- endcapture -%} +
+ Rerun a job with SSH to directly access the build environment. +
+
-{% include two-up.html title="3. SSH into your build" content=content imageURL=SSH-into-build imageAlt="Rerun Job with SSH" %} ++++ -That’s a wrap! We hope you’re up and running and more confident using CircleCI. To continue your progress, check out the resources below or link:https://support.circleci.com/hc/en-us[ask for help]. -//// - pass:[] [#next-steps] diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/commit-and-run.png b/jekyll/assets/img/docs/getting-started-guide-exp/commit-and-run.png new file mode 100644 index 00000000000..81887224198 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/commit-and-run.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/create-project.png b/jekyll/assets/img/docs/getting-started-guide-exp/create-project.png index 6708c7f0d5e..208a0aea773 100644 Binary files a/jekyll/assets/img/docs/getting-started-guide-exp/create-project.png and b/jekyll/assets/img/docs/getting-started-guide-exp/create-project.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/expand-step.png b/jekyll/assets/img/docs/getting-started-guide-exp/expand-step.png new file mode 100644 index 00000000000..d4962ffe9f3 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/expand-step.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/invite.png b/jekyll/assets/img/docs/getting-started-guide-exp/invite.png new file mode 100644 index 00000000000..dc867a41854 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/invite.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/pass-pipeline.png b/jekyll/assets/img/docs/getting-started-guide-exp/pass-pipeline.png new file mode 100644 index 00000000000..4d3b87563f5 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/pass-pipeline.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/select-config.png b/jekyll/assets/img/docs/getting-started-guide-exp/select-config.png index 16659523250..5ed17c2c3bf 100644 Binary files a/jekyll/assets/img/docs/getting-started-guide-exp/select-config.png and b/jekyll/assets/img/docs/getting-started-guide-exp/select-config.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/set-up-project.png b/jekyll/assets/img/docs/getting-started-guide-exp/set-up-project.png new file mode 100644 index 00000000000..2ff4fac7a30 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/set-up-project.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/setup-pipeline.png b/jekyll/assets/img/docs/getting-started-guide-exp/setup-pipeline.png new file mode 100644 index 00000000000..0db67d92d0d Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/setup-pipeline.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/ssh-rerun.png b/jekyll/assets/img/docs/getting-started-guide-exp/ssh-rerun.png new file mode 100644 index 00000000000..3fa2c78d9a8 Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/ssh-rerun.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/steps.png b/jekyll/assets/img/docs/getting-started-guide-exp/steps.png new file mode 100644 index 00000000000..579136a2eba Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/steps.png differ diff --git a/jekyll/assets/img/docs/getting-started-guide-exp/validate-config.png b/jekyll/assets/img/docs/getting-started-guide-exp/validate-config.png new file mode 100644 index 00000000000..eb4214b5f3c Binary files /dev/null and b/jekyll/assets/img/docs/getting-started-guide-exp/validate-config.png differ