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.
In the connect your code window, select the GitHub tile.
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. If your GitHub organization has more than 100 repositories, select the Only select repositories option. There is a known issue where GitHub organizations with more than 100 repositories cannot view their repositories in CircleCI if they select the "All repositories" option when installing the CircleCI GitHub App.
Give your project a name, select the GitHub repository you would like to connect, and select Create Project.
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.
When the custom configuration file has been generated, you have some options:
Select Commit and Run to commit your custom configuration file on a new branch called circleci-project-setup and then land on the pipelines page.
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 to navigate to the 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.
In the connect your code window, select the GitLab tile, then choose GitLab Cloud.
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.
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.
In the connect your code window, select the GitLab tile, then choose 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.
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:
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.
Set up a project
If you authenticated CircleCI with either the GitHub OAuth app, or Bitbucket, 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.
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 an 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.
