Your First Green Build
This document provides a step-by-step tutorial for getting your first successful (green) build on CircleCI.
- Creating a repository
- Setting up CircleCI
- Digging into your first pipeline
- Collaborating with teammates
Prerequisites for running your first build
- Some basic knowledge of Git.
- A GitHub or Bitbucket account, of which you are logged into. We will use GitHub for this guide but you can follow the equivalent processes for Bitbucket if required.
- An account on CircleCI.
- Some basic terminal or
bash
knowledge and prior experience using the command line is helpful.
Creating a repository
Begin by creating a new repository on GitHub. You may skip this section if you intend to use an existing repository.
- Navigate to GitHub and create a new repository.
- Input the name of your repository, in this case “hello-world”, then click Initialize this repository with a README. Finally, click Create repository.
Setting up CircleCI
If you have not yet, create an account on CircleCI by navigating to the signup page and clicking on Sign Up with GitHub.
- Navigate to the CircleCI Project Page.
- If you created your new repository under an organization you will need to select the organization name when you login to CircleCI.
-
Once on the Project page, find the project you are using, in our case
hello-world
, and click Set Up Project. -
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. For this example, because we have an empty repository, we will use the
Hello World
configuration example at the bottom of the list.Note: Based on which language you choose you can view related documentation in the sidebar on the right of the screen
- Click Commit and Run. This will create a file
.circleci/config.yml
at the root of your repository on a new branch calledcircle-ci-setup
. If you are happy with this configuration you can merge it into your main branch later, or continue to make changes.
Digging into your first pipeline
You should see your pipeline start to run automatically—and pass! So, what just happened? Click on the green Success button on your pipeline to investigate the following parts of the run:
-
Which workflows ran?: After clicking Success, we are taken to a page listing the jobs that ran. If this is your first build, you probably only ran one job (which automatically runs inside one workflow). In our case, we only ran one job, called
welcome/run
. Click onwelcome/run
and let’s investigate the steps of our job. -
Spin up environment: CircleCI used an orb to help provide some defaults for this project. By using an orb, we can get quick access to common configuration. In this case,
circleci/welcome-orb@0.4.1
provides a “pre-built” job you can run which simply greets the user. -
Views step results: Every job is made up of a series of steps - some steps, like
checkout
are special, reserved commands in CircleCI. Other steps are specified by a user to achieve a specific purpose. Because we are using thewelcome
orb, we don’t see custom steps; they are configured in the orb. But no problem! We can view the source of an orb online.
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!
Let’s get a bit more complex. Let’s edit our .circleci/config.yml
file now. On
GitHub, it is possible to edit files directly. Use the URL below and substitute
the name of your repository and username (replace the text with {brackets}
) and
then paste it in your browser. If you are already familiar with Git, use your
text-editor and push your changes with git.
https://github.com/{username}/{repo}/edit/circleci-project-setup/.circleci/config.yml
Let’s use the Node orb. Paste the following into your config.yml
version: 2.1
orbs:
node: circleci/node@1.1
jobs:
build:
executor:
name: node/default
tag: '10.4'
steps:
- checkout
- node/with-cache:
steps:
- run: npm install
- run: npm run test
Then, commit your change in the GitHub editor and return to the Projects page in CircleCI. You should see a new pipelines running… and it will fail! What’s going on?
The Node orb runs some common Node tasks. Because we are working with an empty
repository, running npm run test
, a Node script, causes our configuration to
fail. How would we fix this? You would need to setup a Node project in your
repository; a topic for another tutorial. You can view several demo
applications that go into more detail on
setting up CircleCI with various languages and frameworks.
Using the workflows functionality
You do not have to use orbs to use CircleCI. The following example details how to create a custom configuration that also uses the workflow feature of CircleCI.
-
Take a moment and read the comments in the code block below. Of course, we do not want to be copying and pasting code without understanding what we are doing. Now, to see Workflows in action, edit your
.circleci/config.yml
file and copy and paste the following text into it.version: 2 jobs: # we now have TWO jobs, so that a workflow can coordinate them! one: # This is our first job. docker: # it uses the docker executor - image: circleci/ruby:2.4.1 # specifically, a docker image with ruby 2.4.1 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference # Steps are a list of commands to run inside the docker container above. steps: - checkout # this pulls code down from GitHub - run: echo "A first hello" # This prints "A first hello" to stdout. - run: sleep 25 # a command telling the job to "sleep" for 25 seconds. two: # This is our second job. docker: # it runs inside a docker image, the same as above. - image: circleci/ruby:2.4.1 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: echo "A more familiar hi" # We run a similar echo command to above. - run: sleep 15 # and then sleep for 15 seconds. # Under the workflows: map, we can coordinate our two jobs, defined above. workflows: version: 2 one_and_two: # this is the name of our workflow jobs: # and here we list the jobs we are going to run. - one - two
-
Commit these changes to your repository and navigate back over to the CircleCI Pipelines page. You should see your CircleCI pipeline running.
-
Click on the running pipeline to view the workflow you have created. You should see that two jobs ran (or are currently running!) concurrently.
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
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
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
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
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/.
Copy the ssh
string from the enabling SSH section of your build. Open a
terminal and paste in the ssh
string.
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>
Collaborating with teammates
It is easy for teammates and collaborators to 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.
See also
Blog
post
on how to validate the CircleCI config.yml
on every commit with a git hook.
CircleCI
- The CircleCI blog.
- What is continuous integration?
- CircleCI on GitHub, Twitter and Facebook