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.
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:
In the CircleCI web app, select Organization Home in the sidebar.
Select Create Project at the top of the page.
Choose an option to match the work you want to do in your project.
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.
Follow the in-app prompts to give your project a name.
Project names must meet the following requirements:
Begin with a letter
3-40 characters long
Contain only letters, numbers, or the following characters " - _ . : ! & + [ ] " ;
If a CircleCI config file exists in your repository already you will be redirected to the pipelines page. Otherwise, CircleCI automatically generates a custom configuration file based on the programming languages and frameworks detected in your selected repository. If CircleCI is unable to generate a custom configuration file, a fallback template is used. Select Commit and Run.
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.
Choose an option to match the work you want to do in your project.
Choose a repo to connect to your project. If you do not see your repo listed, select Add to access repositories from GitHub. Select GitLab and then Authorize in GitLab
In the Create New Project window, you have some options:
If you see a blue Connect button rather than your GitLab username, select Connect to redirect to GitLab and authorise the connection.
The Project Name field (bottom of the window) is automatically populated with the name of your repository, but you can change this if required.
Project names must meet the following requirements:
Begin with a letter
3-40 characters long
Contain only letters, numbers, or the following characters " - _ . : ! & + [ ] " ;
Use the repository dropdown menu to tell CircleCI where your code is stored.
Choose an option for managing your .circleci/config.yml file:
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.
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.
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.
Choose an option to match the work you want to do in your project.
Choose a repo to connect to your project. If you do not see your repo listed, select Add to access repositories from GitHub. Select GitLab self-managed and then Authorize in GitLab self-managed
In the Create New Project window, you have some options:
If this is your first GitLab self-managed project you will now set up your integration:
Verify your GitLab URL
Generate an add a personal access token
Add your known hosts, following the instructions in the app
The Project Name field (bottom of the window) is automatically populated with the name of your repository, but you can change this if required.
Project names must meet the following requirements:
Begin with a letter
3-40 characters long
Contain only letters, numbers, or the following characters " - _ . : ! & + [ ] " ;
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.yml file 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.
For guidance on creating a config.yml file, see the following pages:
Bitbucket Data Center support is in closed preview. To get access, sign up here.
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.
Choose an option to match the work you want to do in your project.
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
On the next screen give your project a descriptive name.
Project names must meet the following requirements:
Begin with a letter
3-40 characters long
Contain only letters, numbers, or the following characters " - _ . : ! & + [ ] " ;
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.
Follow these steps to set up a new project in CircleCI:
In the CircleCI web app, select Organization Home in the sidebar.
Select Set up a project.
Find your project in the list and select Set Up Project.
Can’t see your project? Select the dark blue section at the top of the window to navigate to your user homepage and select an organization.
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.
Faster: Commit a starter CI pipeline to a new circleci-project-setup branch of your repository.
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, either edit the .circleci/config.yml file in your repository, or select the ellipsis next your project in the Projects dashboard and choose Configuration File. This opens the CircleCI configuration editor, from where you can edit and commit your config.yml file. You can also access the configuration editor using the Edit Config button from a the Pipelines page when you have a project and branch selected.
