Getting Started Introduction
This document provides a step-by-step tutorial for getting your first successful (green) build on CircleCI 2.0.
- Creating a Repository
- Adding a .yml File
- Setting up Your Build on CircleCI
- Running Your First CircleCI Build!
Prerequisites for Running Your First Build
- Some basic knowledge of Git and an existing GitHub.com account or the ability to create one. This procedure uses a new GitHub repository, but CircleCI also supports the use of Bitbucket.
- Some basic terminal or
bashknowledge and prior experience using the command line is helpful.
Creating a Repository
- Navigate to your account on GitHub.com
- Go to the Repositories tab and then select New or navigate directly to https://github.com/new.
- Select Initialize this repository with a README and click the Create repository button.
Adding a .yml File
CircleCI uses a YAML file to identify how you want your testing environment set up and what tests you want to run.
On CircleCI 2.0, this file must be called
config.yml and must be in a hidden folder called
.circleci. On Mac, Linux, and Windows systems, files and folders whose names start with a period are treated as system files that are hidden from users by default.
To create the file and folder on GitHub, click the Create new file button on the repo page and type
.circleci/config.yml. You should now have in front of you a blank
config.ymlfile in a
To start out with a simple
config.yml, copy the text below into the file editing window on GitHub:
version: 2 jobs: build: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A first hello"
Commit the file by entering comments and clicking the Commit New File button.
- image: circleci/ruby:2.4.1 text tells CircleCI what Docker image to use when it builds your project. CircleCI will use the image to boot up a “container” — a virtual computing environment where it will install any languages, system utilities, dependencies, web browsers, and tools, that your project might need to run.
Setting up Your Build on CircleCI
For this step, you will need a CircleCI account. If you already have a CircleCI account then you can navigate to your dashboard, or if you are using CircleCI Server substitute your hostname:
https://<your-circleci-hostname>.com/dashboard. If you don’t have an account yet, visit the CircleCI signup page and click “Start with GitHub”. You will need to give CircleCI access to your GitHub account to run your builds.
Next, you will be given the option of following any projects you have access to that are already building on CircleCI (this would typically apply to developers connected to a company or organization’s GitHub account). On the next screen, you’ll be able to add the repo you just created as a new project on CircleCI.
To add your new repo, ensure that your GitHub account is selected in the dropdown in the upper-left, Select the Add Projects page, and find the repository you just created in the list (you can also search for it), then click the Set Up Project button next to it.
On the following screen, choose a language from the dropdown to get a pre-populated config.yml file with suggested best-practices for your project. If the language you are using is not in the list, click the “Use Hello World” button at the bottom of the list. Copy the YAML configuration that appears and save it as a file called “config.yml” in a folder named
.circleciin the root of your repository’s directory.
Git push your new
config.ymlfile to your VCS. You are ready to start building! Click the button “Start Building” and confirm in the modal that your repository is ready to build.
Running Your First CircleCI Build!
You should see your build start to run automatically—and pass! So, what just happened? Click on the green Success button on the CircleCI dashboard to investigate the following parts of the run:
Spin up environment: CircleCI used the
circleci/ruby:2.4.1Docker image to launch a virtual computing environment.
Checkout code: CircleCI checked out your GitHub repository and “cloned” it into the virtual environment launched in Step 1.
echo: This was the only other instruction in your
config.ymlfile: CircleCI ran the echo command with the input “A first hello” (echo, does exactly what you’d think it would do).
Even though there was no actual source code in your repo, and no actual tests configured in your
config.yml, CircleCI considers your build to have “succeeded” because all steps completed successfully (returned an exit code of 0). Most projects are far more complicated, oftentimes with multiple Docker images and multiple steps, including a large number of tests. You can learn more about all the possible steps one may put in a
config.yml file in the Configuration Reference.
Breaking Your Build!
config.yml file in the GitHub editor for simplicity and replace
echo "A first hello" with
notacommand. Click the Commit change button in the GitHub editor. When you navigate back to the Builds page in CircleCI, you will see that a new build was triggered. This build will fail with a red Failed button and will send you a notification email of the failure.
Using the Workflows Functionality
To see Workflows in action, edit your
.circleci/config.ymlfile. After you have the file in edit mode in your browser window, select the text from
buildand onwards in your file and copy and paste the text to duplicate that section. That should look similar to the code block below:
version: 2 jobs: build: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A first hello" build: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A first hello"
Next, rename your two jobs so that they have different names. In this example they are named
two. Change the contents of the echo statements to something different. To make the build take a longer period of time we can add a system
workflowssection to your
config.ymlfile. The workflows section can be placed anywhere in the file. Typically it is found either at the top or the bottom of the file.
version: 2 jobs: one: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A first hello" - run: sleep 25 two: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A more familiar hi" - run: sleep 15 workflows: version: 2 one_and_two: jobs: - one - two
Commit these changes to your repository and navigate back over to the CircleCI dashboard.
Click on the link for your workflow to see that these two jobs run in parallel.
Read more about workflows in the Orchestrating Workflows documentation.
Adding Some Changes to use the Workspaces Functionality
Each workflow has an associated workspace which can be used to transfer files to downstream jobs as the workflow progresses. You can use workspaces to pass along data that is unique to this run and which is needed for downstream jobs. Try updating
config.yml to the following:
version: 2 jobs: one: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A first hello" - run: mkdir -p my_workspace - run: echo "Trying out workspaces" > my_workspace/echo-output - persist_to_workspace: # Must be an absolute path, or relative path from working_directory root: my_workspace # Must be relative path from root paths: - echo-output two: docker: - image: circleci/ruby:2.4.1 steps: - checkout - run: echo "A more familiar hi" - attach_workspace: # Must be absolute path or relative path from working_directory at: my_workspace - run: | if [[ $(cat my_workspace/echo-output) == "Trying out workspaces" ]]; then echo "It worked!"; else echo "Nope!"; exit 1 fi workflows: version: 2 one_and_two: jobs: - one - two: requires: - one
Read more about workspaces here.
SSH into Your Build
If you are comfortable with the terminal, you can SSH directly into your CircleCI jobs to troubleshoot issues with your builds by rerunning your build with the SSH enabled option.
Note that you will need to add your SSH keys to your GitHub account: https://help.github.com/articles/connecting-to-github-with-ssh/.
ssh string from the enabling SSH section of your build. Open a terminal and paste in the
Using some of the following commands, see if you can find and view the contents of the file you created using workspaces:
pwd # print what directory, find out where you are in the file system ls -al # list what files and directories are in the current directory cd <directory_name> # change directory to the <directory_name> directory cat <file_name> # show me the contents of the file <file_name>
Blog post on how to validate the CircleCI
config.yml on every commit with a git hook.
- The CircleCI blog and how to follow it
- Relevant blog post
- Our other social media and GitHub