Create a project in CircleCI
1 month ago
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:
-
If you see a Set up a project button, follow steps to Set up a project below.
-
If you see a Create Project button, follow steps to Create a project below.
| Using CircleCI server? Use the Set up a project steps below. Rather than Organization Home you will see Dashboard in the web app sidebar. |
Create a project
| If you have integrated your code with the CircleCI GitHub App, GitLab, or Bitbucket Data Center, the steps in this section apply to you. |
Choose steps to follow below, depending on where your code is stored:
-
GitHub App
-
GitLab Cloud
-
GitLab self-managed
-
Bitbucket Data Center
Follow these steps to create a new project in CircleCI:
-
In the CircleCI web app, select Organization Home in the sidebar.
-
Select Create Project at the top of the page, or anywhere in the Create a project card if this is your first project.
Figure 1. Create a project button
Figure 2. Create a project card view when creating your first project -
Choose an option to match the work you want to do in your project.
Figure 3. Tell CircleCI what your project is for -
Give your project a descriptive name and then select Next: Set up a pipeline.
Figure 4. Name your project -
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.
Figure 5. Set up a pipeline -
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
First GitHub project? If this is the first GitHub project you are creating, you will be redirected to GitHub and asked to install and authorise the CircleCI GitHub App. At this point you can choose to connect CircleCI to all your repositories, or select a subset of repositories to connect. This is a one-time action that can be done by an organization administrator or someone who has admin access to a repository in your org. 
Figure 6. Choose a repo to connect your code to your project -
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.
Figure 7. Set up your CircleCI config file -
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.
Figure 8. Set up triggers for your pipeline -
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.
Figure 9. Review and finish setup
Once your project is created you will land on your pipelines page.
Follow these steps to create a new project in CircleCI:
-
In the CircleCI web app, select Organization Home in the sidebar.
-
Select Create Project at the top of the page, or anywhere in the Create a project card if this is your first project.
Figure 10. Create a project button
Figure 11. Create a project card view when creating your first project -
Choose an option to match the work you want to do in your project.
Figure 12. Tell CircleCI what your project is for -
Give your project a descriptive name and then select Next: Set up a pipeline.
Figure 13. Name your project -
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.
Figure 14. Set up a pipeline -
Choose a repo to connect to your project. If you do not see your repo listed, select Add or Connect to GitLab Cloud to authorise access to your GitLab repositories.
Choose a repo to connect your code to your project
Figure 15. Choose a repo to connect your code to your projectFirst GitLab project? If you are creating the first GitLab project for your org, you will be redirected to GitLab to authorise the integration. This is a one-time action that can be done by an organization administrator or someone who has admin access to a repository in your org. -
In the Create New Project window, ensure you have the right repo selected in the dropdown. If you have a CircleCI config file already available in your repo, CircleCI will detect it. If not you can select an option for adding one:
Figure 16. Set up a new GitLab project-
Fastest: Use a config file that already exists in your repository.
-
Faster: Let CircleCI pick a configuration file for you, and commit this to a new branch in you repository.
-
Fast: View and edit a starter config file in the CircleCI web app and commit that to your repository yourself.
-
-
Select Create Project at the bottom of the window.
-
If you chose the fastest/faster options you will now be on the pipelines page of the CircleCI web app. If you chose "fast" you have some options:
-
Select Commit and Run to commit your custom configuration file on a new branch called
circleci-project-setup.
Figure 17. Use a generated config file -
Select Use Existing Config for the option to download the generated config and instructions to commit this or another CircleCI configuration file to your repository directly. The select Start Building.
Figure 18. Instructions for using an existing config file
-
Follow these steps to create a new project in CircleCI:
-
In the CircleCI web app, select Organization Home in the sidebar.
-
Select Create Project at the top of the page, or anywhere in the Create a project card if this is your first project.
Figure 19. Create a project button
Figure 20. Create a project card view when creating your first project -
Choose an option to match the work you want to do in your project.
Figure 21. Tell CircleCI what your project is for -
Give your project a descriptive name and then select Next: Set up a pipeline.
Figure 22. Name your project -
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.
Figure 23. Set up a pipeline -
Choose a repo to connect to your project. If you do not see your repo listed, select Add or Connect to GitLab self-managed to access repositories from your GitLab self-managed instance. Select GitLab self-managed and then Authorize in GitLab self-managed
Figure 24. Choose a repo to connect your code to your project
Figure 25. Authorize GitLab self-managed -
In the Create New Project window, you have some options:
Figure 26. Set up your new GitLab self-managed project-
Use the repository dropdown menu to tell CircleCI where your code is stored.
-
Select Create Project. You will then be redirected to the Pipelines page.
-
The express CircleCI configuration setup is not currently available for GitLab self-managed projects. You will need to add a
.circleci/config.ymlfile in your repository if it has not yet been set up. If the repository you selected already contains a.circleci/config.yml, push a commit to see your pipeline on the dashboard.
-
Follow these steps to create a new project in CircleCI:
-
In the CircleCI web app, select Organization Home in the sidebar.
-
Select Create Project at the top of the page, or anywhere in the Create a project card if this is your first project.
Figure 27. Create a project button
Figure 28. Create a project card view when creating your first project -
Choose an option to match the work you want to do in your project.
Figure 29. Tell CircleCI what your project is for -
Give your project a descriptive name and then select Next: Set up a pipeline.
Figure 30. Name your project -
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.
Figure 31. Set up a pipeline -
Choose a repo to connect to your project. If you do not see your repo listed, select Add to access repositories from GitHub. Select Bitbucket Data Center and then Authorize in Bitbucket Data Center
Figure 32. Access Bitbucket data center repos -
Next, follow the steps on the Bitbucket integration setup page to set up the following:
-
An integration with your Bitbucket Data Center instance (if not already set up for your org).
-
Set up a pipeline and trigger for your project.
-
Add a configuration file to your repo.
-
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 . For more information, see the Pipelines overview.
Set up a project
| If you authenticated CircleCI with either the GitHub OAuth app or Bitbucket Cloud, or if you use CircleCI server, the steps in this section apply to you. |
Follow these steps to set up a new project in CircleCI:
-
In the CircleCI web app, select Organization Home in the sidebar. The equivalent option in CircleCI server is Dashboard
-
Select Set up a project.
Figure 33. Set up a project -
Find your project in the list and select Set Up Project.
Can’t see your project? Select the CircleCI logo at the top of the window to navigate to your user homepage and select an organization.
Figure 34. Access your user homepage -
Choose a
config.ymloption in the modal. You can choose from the following:-
Fastest: Use a CircleCI
.circleci/config.ymlyou have already committed to your repository. For guidance on creating aconfig.ymlfile, see the Configuration Introduction. You will also need to specify a branch. -
Faster: Commit a starter CI pipeline to a new
circleci-project-setupbranch of your repository. -
Fast: View, edit, and commit a template
config.yml.
-
-
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.ymlfile. -
Access the configuration editor using the Edit Config button from a the Pipelines page when you have a project and branch selected.
