Create a project in CircleCI

1 week ago8 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud
Server v4+
This document is applicable to CircleCI Server v4+

This guide gets you started with creating a new project in CircleCI.

Prerequisites

  • A CircleCI account connected to your code. You can sign up for free.

  • Code you want to build on CircleCI.

Build a new project on CircleCI

The authorization method used to set up your CircleCI account determines the definition of "project" in CircleCI, as well as the permissions management processes available to you:

On the Organization Home page, check which option you see:

Create a project

Choose steps to follow below, depending on where your code is stored:

Follow these steps to create a new project in CircleCI:

  1. In the CircleCI web app, select Organization Home in the sidebar.

  2. Select Create Project at the top of the page, or anywhere in the Create a project card if this is your first project.

    Create a project
    Figure 1. Create a project button
    Create your first project
    Figure 2. Create a project card view when creating your first project
  3. Choose an option to match the work you want to do in your project.

    Screenshot showing options to choose what you want to do in your project
    Figure 3. Tell CircleCI what your project is for
  4. Give your project a descriptive name and then select Next: Set up a pipeline.

    Screenshot showing options to enter project details
    Figure 4. Name your project
  5. Next, set up your first pipeline for your project. Pipelines orchestrate executable commands and scripts for your CI/CD processes. The first step is to name your pipeline. Use a name that describes the purpose of the pipeline, for example, build-and-test. Then select Next: Choose a repo.

    Screenshot showing options to set up your pipeline
    Figure 5. Set up a pipeline
  6. Choose a repo to connect to your project.

    If you do not see your repo listed, select Add to access repositories from GitHub. Select GitHub and then Authorize in GitHub

    Choose a repository window with option to add another VCS
    Figure 6. Choose a repo to connect your code to your project
  7. In this next step CircleCI will prepare a config file for you, unless your repo already contains a CircleCI config file. In a later step you will commit this config to your repo on a new branch. If you do already have a CircleCI config file in your repo it will be displayed. Once you have your config, select Next: set up your triggers.

    Screenshot showing options to set up your config file
    Figure 7. Set up your CircleCI config file
  8. Set up triggers for your pipeline. A single GitHub App trigger is set up by default to build your project on every commit to your repo. You can add more triggers at this point too.

    Screenshot showing options to set up your triggers
    Figure 8. Set up triggers for your pipeline
  9. Next you can review everything you have just set up, then select Commit config and run, or Finish setup if you already have a config file in your repo.

    Screenshot showing options to review and commit your config
    Figure 9. Review and finish setup

Once your project is created you will land on your pipelines page.

CircleCI uses the specified .circleci/config.yml file to run your pipeline. You can see the output on the pipelines page. To make changes to your pipeline, edit the .circleci/config.yml file in your repository.

Through creating a project and connecting your code you have set up your pipeline and a trigger. The default trigger runs your pipeline when a change is committed to your code. You can create more triggers at Project settings  Triggers. For more information, see the Pipelines overview.

Set up a project

Follow these steps to set up a new project in CircleCI:

  1. In the CircleCI web app, select Organization Home in the sidebar. The equivalent option in CircleCI server is Dashboard

  2. Select Set up a project.

    Set up a project button
    Figure 33. Set up a project
  3. Find your project in the list and select Set Up Project.

  4. Choose a config.yml option in the modal. You can choose from the following:

    • Fastest: Use a CircleCI .circleci/config.yml you have already committed to your repository. For guidance on creating a config.yml file, see the Configuration Introduction. You will also need to specify a branch.

    • Faster: Commit a starter CI pipeline to a new circleci-project-setup branch of your repository.

    • Fast: View, edit, and commit a template config.yml.

  5. Select Set Up Project.

CircleCI uses the specified .circleci/config.yml file to run your pipeline. You can see the output in the CircleCI dashboard.

To make changes to your pipeline, choose one of the following:

  • Edit the config file in your repository,

  • Select the ellipsis () next your project in the Pipelines or Projects dashboard and choose Configuration File. This opens the CircleCI configuration editor, from where you can edit and commit your config.yml file.

  • Access the configuration editor using the Edit Config button from a the Pipelines page when you have a project and branch selected.

Edit Configuration File
Figure 35. Access and edit a config file