# Create a project in CircleCI

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](https://circleci.com/signup/).
    
*   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 **Home** page, check which option you see:

*   If you see a **Set up a project** button, follow steps to [Set up a project](#set-up-a-project) below.
    
*   If you see a **Create Project** button, follow steps to [Create a project](#create-a-project) below.
    

Using CircleCI Server? Use the [Set up a project](#set-up-a-project) steps below. Rather than Home you will see Dashboard in the web app sidebar.

### Create a project

If you are using a `circleci` type organization, the steps in this section apply to you.

To check your organization type, check your organization slug at **Organization settings**  **Overview**. `github` and `bitbucket` type organizations are OAuth authenticated orgs and the organization slug is structured as follows:

*   `github/<your-org-name>` or `gh/<your-org-name>`
    
*   `bitbucket/<your-org-name>` or `bb/<your-org-name>`
    

An organization slug for a `circleci` type organization is in the following format:

*   `circleci/<UID>`
    

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

**GitHub App:**

Follow these steps to create a new project in CircleCI:

1.  In the [CircleCI web app](https://app.circleci.com/home), select **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.
    
    Figure 1. Create a project button
    
    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.
    
    Figure 3. Tell CircleCI what your project is for
    
4.  Give your project a descriptive name and then select **Next: Set up a pipeline**.
    
    **Project names** must meet the following requirements:
    
    *   Begin with a letter.
        
    *   Be 3-40 characters long.
        
    *   Contain only letters, numbers, or the following characters: `" - _ . : ! & + [ ] " ;`.
        
    
    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**.
    
    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**
    
    **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
    
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**.
    
    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](https://circleci.com/docs/guides/orchestrate/set-up-triggers/) at this point too.
    
    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.
    
    Figure 9. Review and finish setup
    

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

**GitLab Cloud:**

**Remove GitLab CI/CD config.** Remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**.

Follow these steps to create a new project in CircleCI:

1.  In the [CircleCI web app](https://app.circleci.com/home), select **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.
    
    Figure 10. Create a project button
    
    Figure 11. 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.
    
    Figure 12. Tell CircleCI what your project is for
    
4.  Give your project a descriptive name and then select **Next: Set up a pipeline**.
    
    **Project names** must meet the following requirements:
    
    *   Begin with a letter.
        
    *   Be 3-40 characters long.
        
    *   Contain only letters, numbers, or the following characters: `" - _ . : ! & + [ ] " ;`.
        
    
    Figure 13. 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**.
    
    Figure 14. Set up a pipeline
    
6.  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 project
    
    **First 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.
    
7.  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.
        
    
8.  Select **Create Project** at the bottom of the window.
    
9.  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
        
    

**GitLab self-managed:**

Before creating a project that you want to integrate with code in a GitLab self-managed instance, you need to set up an integration with your GitLab self-managed instance. See the [Organization Integration Setup](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration) page for more information.

**Remove GitLab CI/CD config** Remove the `.gitlab-ci.yml` file from projects you integrate with CircleCI. This prevents you from having CI/CD builds happening in both systems. There is an option to _disable_ GitLab CI/CD for a project in the GitLab UI but using this is **not recommended**.

Follow these steps to create a new project in CircleCI:

1.  In the [CircleCI web app](https://app.circleci.com/home), select **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.
    
    Figure 19. Create a project button
    
    Figure 20. 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.
    
    Figure 21. Tell CircleCI what your project is for
    
4.  Give your project a descriptive name and then select **Next: Set up a pipeline**.
    
    **Project names** must meet the following requirements:
    
    *   Begin with a letter.
        
    *   Be 3-40 characters long.
        
    *   Contain only letters, numbers, or the following characters: `" - _ . : ! & + [ ] " ;`.
        
    
    Figure 22. 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**.
    
    Figure 23. 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 your GitLab self-managed instance.
    
    Figure 24. Choose a repo to connect your code to your project
    
    Select **GitLab self-managed** and then **Authorize in GitLab self-managed**
    
    Figure 25. Authorize GitLab self-managed
    
7.  In the Create New Project window, you have some options:
    
    Figure 26. Set up your new GitLab self-managed project
    
    If you set up your GitLab self-managed instance you will see your instance URL and known\_hosts. If not see the [Integration Instructions](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration).
    
    *   Generate and add a personal access token with the `api` scope.
        
        *   Use the Repository dropdown menu to tell CircleCI where your code is stored.
            
        *   Use the Branch dropdown to tell CircleCI which branch to use for your pipeline.
            
        *   Select **Save**. 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 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:
            
            *   [Configuration Introduction](https://circleci.com/docs/guides/getting-started/config-intro/)
                
            *   [Sample Config.yml Files](https://circleci.com/docs/guides/toolkit/sample-config/)
                
            *   [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/)
                
            
        
    

**Bitbucket Data Center:**

Before creating a project that you want to integrate with code in a Bitbucket Data Center instance, you need to set up an integration with your Bitbucket Data Center instance. See the [Bitbucket Data Center Integration Setup](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration) page for more information.

Follow these steps to create a new project in CircleCI:

1.  In the [CircleCI web app](https://app.circleci.com/home), select **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.
    
    Figure 27. Create a project button
    
    Figure 28. 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.
    
    Figure 29. Tell CircleCI what your project is for
    
4.  Give your project a descriptive name and then select **Next: Set up a pipeline**.
    
    **Project names** must meet the following requirements:
    
    *   Begin with a letter.
        
    *   Be 3-40 characters long.
        
    *   Contain only letters, numbers, or the following characters: `" - _ . : ! & + [ ] " ;`.
        
    
    Figure 30. 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**.
    
    Figure 31. Set up a pipeline
    
6.  Choose a repo to connect to your project. If you do not see your repo listed, select **Add**. Select **Bitbucket Data Center** and then **Authorize in Bitbucket Data Center**.
    
    Figure 32. Access Bitbucket data center repos
    
7.  To set up your project you will need to create a project HTTP access token with the project admin scope. Create this under Projects in Bitbucket. For more information, see the [Bitbucket docs](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI.
    
    If you set up your Bitbucket Data Center instance you will see your instance URL and known\_hosts. If not see the [Integration Instructions](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration).
    
    *   Use the repository dropdown menu to tell CircleCI where your code is stored.
        
    *   Use the Branch dropdown to tell CircleCI which branch to use for your pipeline.
        
    *   Select **Save**. You will then be redirected to the Pipelines page.
        
    *   The express CircleCI configuration setup is not currently available for Bitbucket Data Center projects. You will need to add a `.circleci/config.yml` file in your repository. If the repository you selected already contains a `.circleci/config.yml`, push a commit to see your pipeline on the dashboard.
        
    

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**  **Project Setup** if your project integrates with GitHub, or at **Project settings**  **Triggers** if it integrates with GitLab or Bitbucket. For more information, see the [Set up Triggers](https://circleci.com/docs/guides/orchestrate/set-up-triggers/) page.

### Set up a project

If you authenticated CircleCI with either the [GitHub OAuth App](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/) or [Bitbucket Cloud](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/), 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:

1.  In the CircleCI web app, select **Home** in the sidebar. The equivalent option in CircleCI Server is **Dashboard**.
    
2.  Select **Set up a project**.
    
    Figure 33. Set up a project
    
3.  Find your project in the list and select **Set Up Project**.
    
    **Not seeing 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
    
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](https://circleci.com/docs/guides/getting-started/config-intro/). 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.
    

Figure 35. Access and edit a config file

## Troubleshooting

This section covers common issues you may encounter when creating a project in CircleCI.

### Repository not visible in the list

If you do not see your repository when trying to connect it to a project, try the following:

*   If you are using the **Set up project** flow, **Check your permissions**. Ensure you have admin access to the repository in your VCS provider. CircleCI requires admin permissions to set up projects.
    
*   If you are using the **Create project** flow **re-authorize your VCS connection**. Select the **Add** button and then select the **Authorize** option for your VCS provider.
    
*   **Verify organization selection**: Select the CircleCI logo at the top of the web app to navigate to your user homepage and confirm you are in the correct organization.
    
*   **Check GitHub App installation**: If using GitHub App, verify the CircleCI app is installed on your github organization and has access to the repository. Go to your github organization settings, select **GitHub Apps**, and check the CircleCI app configuration.
    

### GitLab CI/CD running alongside CircleCI

If you are experiencing duplicate builds or conflicts:

1.  **Remove the GitLab CI/CD config file**: Delete the `.gitlab-ci.yml` file from your repository. This prevents GitLab from running its own CI/CD pipelines alongside CircleCI.
    
2.  **Commit and push the change**: After removing the file, commit and push the change to your repository.
    

Do not use the option to disable GitLab CI/CD in the GitLab UI. Remove the `.gitlab-ci.yml` file instead to prevent conflicts.

### Self-managed instance connection problems

For GitLab self-managed and Bitbucket Data Center integrations, if you encounter connection issues:

1.  **Verify instance URL and known\_hosts**: Ensure your self-managed instance URL and known\_hosts are correctly configured. If these are not visible during project creation, complete the integration setup first. See the [Integration Setup](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#vcs-integration) page for more information.
    
2.  **Check personal access token**: For GitLab self-managed, verify your personal access token has the `api` scope and has not expired. You may need to generate a new token in your GitLab instance.
    
3.  **Check HTTP access token**: For Bitbucket Data Center, verify your HTTP access token has the project admin scope and has not expired. Generate tokens under Projects in your Bitbucket Data Center instance.
    
4.  **Verify network connectivity**: Ensure CircleCI can reach your self-managed instance. Check firewall rules, network policies, and any VPN requirements that may block the connection.
    

### Incomplete project setup

If you started creating a project but did not complete the guided setup process, you may have a project that is not fully configured. Symptoms include:

*   Project appears in your project list but has no pipelines.
    
*   Project has no triggers configured.
    
*   Project is not connected to a repository.
    

To resolve this issue, choose one of the following options:

**Option 1: Complete the setup process**

1.  Navigate to **Project settings**  **Project Setup** (for GitHub App projects) or **Project settings**  **Pipelines** (for GitLab and Bitbucket projects).
    
2.  Follow the prompts to complete the remaining setup steps:
    
    *   Connect your code repository in the Checkout source field if not already connected.
        
    *   Commit a CircleCI configuration file to your repository and update the config file path and config source fields.
        
    *   Set up triggers for your pipeline.
        
    
3.  Push a commit to your repository or use the **Trigger Pipeline** button to trigger your first pipeline.
    

**Option 2: Delete the project and start over**

1.  Navigate to **Project settings**  **Overview**.
    
2.  Scroll to the bottom of the page and select **Delete Project**.
    
3.  Confirm the deletion.
    
4.  Follow the steps in the [Create a project](#create-a-project) or [Set up a project](#set-up-a-project) section to create your project again, ensuring you complete all setup steps.
    

## See also

*   [Configuration Introduction](https://circleci.com/docs/guides/getting-started/config-intro/)
    
*   [Sample Config.yml Files](https://circleci.com/docs/guides/toolkit/sample-config/)
    
*   [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/)
    
*   [Using the CircleCI Configuration Editor](https://circleci.com/docs/guides/getting-started/config-editor/)