Your First Green Build

Follow this step-by-step guide to get your first successful green build on CircleCI using a GitHub repository.

• Create a repository
• Set up CircleCI
• Dig into your first pipeline
• Collaborating with teammates

Prerequisites for running your first build

• Some basic knowledge of Git.
• A GitHub or Bitbucket account. We will use GitHub in this guide but you can follow the equivalent steps for Bitbucket if necessary.
• An account on CircleCI, connected to your version control system. If you do not already have an account, visit the Signup page to create one (optional: read through the Sign Up & Try instructions).
• Prior experience using the terminal or command line is helpful, as well as some basic bash knowledge.

Create a repository

1. Log in to GitHub and begin the process to create a new repository.
2. Enter a name for your repository (for example, hello-world).
3. Select the option to initialize the repository with a README file.
4. Finally, click Create repository.

There is no need to add any source code for now.

Set up CircleCI

1. Navigate to the CircleCI Projects page. If you created your new repository under an organization, you will need to select the organization name.
2. You will be taken to the Projects dashboard. On the dashboard, select the project you want to set up (hello-world).
3. Select the option to commit a starter CI pipeline to a new branch, and click Set Up Project. This will create a file .circleci/config.yml at the root of your repository on a new branch called circleci-project-setup.

Congratulations! You will soon have your first green build. If you are happy with this configuration, you can merge it into your main branch later.

Dig into your first pipeline

So, what just happened?

1. On your project’s pipeline page, click the green Success button, which brings you to the workflow that ran (say-hello-workflow).
2. Within this workflow, the pipeline ran one job, called say-hello. Click say-hello to see the steps in this job:
   a. Spin up environment
   b. Preparing environment variables
   c. Checkout code
   d. Say hello

Every job is made up of a series of steps. Some steps, like checkout, are special, reserved commands in CircleCI. The example config uses both the reserved checkout and run steps. Custom steps can also be defined within a job to achieve a user-specified purpose.

Even though there is no actual source code in your repo, and no actual tests configured in your .circleci/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 .circleci/config.yml file in the Configuration Reference.

Break your build!

In this section, you will edit the .circleci/config.yml file and see what happens if a build does not complete successfully.

It is possible to edit files directly on GitHub. Open the URL below in a browser, substituting your username (or organization) and the name of your repository (replace the text with {brackets}). Or, if you are comfortable with Git and the command line, use your text editor and push your changes in the terminal.

https://github.com/{username}/{repo}/edit/circleci-project-setup/.circleci/config.yml

Let’s use the Node orb. Replace the existing config by pasting the following code:

version: 2.1
orbs:
  node: circleci/node@4.7.0
jobs:
  build:
    executor:
      name: node/default
      tag: '10.4'
    steps:
      - checkout
      - node/with-cache:
          steps:
            - run: npm install
      - run: npm run test

Commit your change, then return to the Projects page in CircleCI. You should see a new pipeline running… and it will fail! What’s going on?

The Node orb runs some common Node tasks. Because you are working with an empty repository, running npm run test, a Node script, causes the configuration to fail. To fix this, you need to set up 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.

Use workflows

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.

1. Take a moment and read the comments in the code block below. Then, 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: cimg/ruby:2.6.8 # specifically, a docker image with ruby 2.6.8
           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: cimg/ruby:3.0.2
           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
   

2. Commit these changes to your repository and navigate back to the CircleCI Pipelines page. You should see your pipeline running.

3. 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.

Add some changes to use workspaces

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: cimg/ruby:3.0.2
        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: cimg/ruby:3.0.2
        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

Learn more about this feature in the Workspaces page.

SSH into your jobs

If you are comfortable with the terminal, you can rerun a CircleCI job with SSH enabled, then SSH directly into your jobs to troubleshoot issues.

• You will need to add your SSH keys to your GitHub account.
• To enable the Rerun Job with SSH option, you will also need to add your SSH keys to the appropriate job. Refer to the Adding SSH Keys to a Job instructions.

Copy the ssh string from the enabling SSH section of your build. Then, paste in and execute the ssh command in the terminal.

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

• Configuration Reference
• CircleCI concepts
• Automate common tasks with orbs