Documentation structure for LLMs (llms.txt)
CircleCI Logo

Create a project in CircleCI

6 days ago
Cloud Server

This guide walks you through creating a new project in CircleCI. Creating a project is the step where you give CircleCI access to the code in your repository, so it can check that code out and run pipelines against it.

Prerequisites

  • A CircleCI account and organization. See the Create an Organization page if you have not created one yet.

  • 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:

Using CircleCI Server? Use the 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. You will see a Create Project button on the Home page.

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

  • GitHub

  • GitLab Cloud

  • GitLab self-managed

  • Cursor Origin

  1. In the CircleCI web app, 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.

  3. 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: " - _ . : ! & + [ ] " ;.

  4. Next, set up your first pipeline for your project. Pipelines define the 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.

  5. Choose a repo for your pipeline. CircleCI checks out the code from this repo when your pipeline runs.

    If you already have a connection, select your repo from the list. To connect an additional provider, select + Add and then choose its tile.

    If you have no connection yet, select your provider’s tile and follow that provider’s instructions. Granting access applies to any project in your organization, and you can update repo access at any time.

    Select the GitHub Cloud tile to get set up. CircleCI redirects you to GitHub, where you install and authorise the CircleCI GitHub App. You can connect CircleCI to all your repositories, or select a subset. An organization administrator, or someone with admin access to a repository in your org, can complete this one-time authorization.

  6. CircleCI prepares 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.

    To run an existing GitHub Actions workflow file instead of a CircleCI config file, select Use existing GitHub Actions workflow file on the Select your config source step. See the Use a GitHub Actions Workflow File as Your Pipeline Configuration page.

  7. 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.

  8. 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.

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

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. The GitLab UI also offers an option to disable GitLab CI/CD for a project, but using this is not recommended.

  1. In the CircleCI web app, 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.

  3. 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: " - _ . : ! & + [ ] " ;.

  4. Next, set up your first pipeline for your project. Pipelines define the 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.

  5. Choose a repo for your pipeline. CircleCI checks out the code from this repo when your pipeline runs.

    If you already have a connection, select your repo from the list. To connect an additional provider, select + Add and then choose its tile.

    If you have no connection yet, select your provider’s tile and follow that provider’s instructions. Granting access applies to any project in your organization, and you can update repo access at any time.

    First GitLab project? Selecting the GitLab Cloud tile redirects you to GitLab to authorise the integration. An organization administrator, or someone with admin access to a repository in your org, can complete this one-time authorization.

  6. 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:

    • 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 your repository.

    • Fast: View and edit a starter config file in the CircleCI web app and commit that to your repository yourself.

  7. Select Create Project at the bottom of the window.

  8. 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. Then select Start Building.

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 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. The GitLab UI also offers an option to disable GitLab CI/CD for a project, but using this is not recommended.

  1. In the CircleCI web app, 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.

  3. 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: " - _ . : ! & + [ ] " ;.

  4. Next, set up your first pipeline for your project. Pipelines define the 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.

  5. Choose a repo for your pipeline. CircleCI checks out the code from this repo when your pipeline runs.

    If you already have a connection, select your repo from the list. To connect an additional provider, select + Add and then choose its tile.

    If you have no connection yet, select your provider’s tile and follow that provider’s instructions. Granting access applies to any project in your organization, and you can update repo access at any time.

    Select the GitLab self-managed tile to authorise access to your instance.

  6. In the Create New Project window, you have some options:

    Create new project window
    Figure 1. 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.

    • 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:

The Cursor Origin integration is in beta.

CircleCI cannot commit files to a Cursor Origin repository. You add your CircleCI config file to the repository yourself, separately from the project creation steps below.

To set up a Cursor Origin project from your terminal instead, see Cursor Origin projects.

  1. In the CircleCI web app, 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.

  3. 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: " - _ . : ! & + [ ] " ;.

  4. Next, set up your first pipeline for your project. Pipelines define the 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.

  5. Choose a repo for your pipeline. CircleCI checks out the code from this repo when your pipeline runs.

    If you already have a connection, select your repo from the list. To connect an additional provider, select + Add and then choose its tile.

    If you have no connection yet, select your provider’s tile and follow that provider’s instructions. Granting access applies to any project in your organization, and you can update repo access at any time.

    Select the Cursor Origin tile to get set up. CircleCI redirects you to Cursor, where you select Install to install the CircleCI app into your Origin codebase. An organization administrator, or someone with admin access to a repository in your codebase, can complete this one-time installation.

  6. Set up the trigger for your pipeline. CircleCI creates one Cursor Origin trigger to get you started. Under "When would you like to run your pipeline?", use the dropdown to select the event that runs your pipeline. The default is All pushes. For the full list of options, see the Cursor Origin Trigger Event Options page.

    You set up one trigger during project creation. You can configure additional triggers once your project is created. See the Set Up Triggers page for more information.

  7. On the Review and finish setup step, set the path to the config file in your repository. The default path is .circleci/config.yml.

Once your project is created you will land on your pipelines page. To see your first pipeline run, push a commit to your repository in Cursor Origin. If you have not added a config file yet, add one at the path you specified and push it.

For guidance on creating a config.yml file, see the following pages:

CircleCI uses the specified config file to run your pipeline. You can see the output on the pipelines page. To make changes to your pipeline, edit the config 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 in your project settings. Use Project settings  Project Setup for GitHub and Cursor Origin projects, or Project settings  Triggers for GitLab and Bitbucket projects. For more information, see the Set Up Triggers page.

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:

  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.

  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.

  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 page. 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 Ellipsis menu iconEllipsis menu icon 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 the Pipelines page when you have a project and branch selected.

Create a project with the CLI

You can also create a project from your terminal using the CircleCI CLI. Two commands create projects, and they differ in scope:

  • circleci onboard walks you through a guided setup. Use it when you want CircleCI to generate a config file, create the project, connect your repository, and set up your first trigger. It can also sign you up and install your VCS integration if you have not done that yet. See Create a project and set it up in one step.

  • circleci project create creates the project record only. Use it in a circleci type organization when your VCS integration is already set up and you want to add the config file and triggers yourself. See Create a project directly.

If you are not sure which command to use, use circleci onboard.

Create a project and set it up in one step

To scaffold a config file, create the project, and add a trigger in one command, run the following from inside your repository:

circleci onboard

circleci onboard prompts you to choose what you want to do, then walks through the whole setup. It does the following:

  • Generates a starter .circleci/config.yml file, if your repository does not already have one.

  • Signs you up for CircleCI, if you are not already signed in.

  • Creates your project and connects your repository.

  • Creates your first pipeline definition and a trigger that runs on all pushes.

To skip the initial prompt, add --scan to set up the current repository, or --signup to only sign up for CircleCI.

CircleCI does not commit the config file for you. When setup finishes, the CLI prints the git commands to run:

git add .circleci/
git commit -m "Add CircleCI config"
git push

Pushing triggers your first pipeline.

Create a project directly

This command applies to circleci type organizations. If you have a github or bitbucket type organization, use circleci onboard instead. Projects in these organizations are imported from your VCS provider rather than created in CircleCI.

To create a CircleCI project without generating a config file or setting up a trigger, run:

circleci project create my-project --org <my-org-slug>  # creates the project record only, no config or trigger

Replace my-project with your project name and <my-org-slug> with your organization slug. For example, gh/myorg, bb/myorg, or circleci/<orgID>. If you omit the project name, CircleCI uses the current git repository’s name.

This only creates the project record in CircleCI. You still need to add a .circleci/config.yml file to your repository and set up a trigger. See the Set Up Triggers page for more information.

This command does not set up a VCS integration, which is what gives CircleCI access to the code in your repositories. If your organization is not yet connected to your VCS provider, either set that connection up first, or use circleci onboard, which can do it for you. For steps, see the Set Up VCS Connections page.

Cursor Origin projects

Both commands work for Cursor Origin projects. Two things are specific to Origin:

  • If the CircleCI Origin app is not yet installed in your Origin codebase, circleci onboard opens a browser to install it, then finds your repository and creates the pipeline definition and trigger. circleci project create does not install the app, so install it first. See the Set Up VCS Connections page.

  • Committing and pushing the config file yourself is required, whichever command you use, for the reason described in the Cursor Origin tab in Create a project.

If you created your project from a directory that is not yet linked to it, run circleci project link to bind the checkout to the project, so other CLI commands resolve it automatically. See the CircleCI CLI guide for more.

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.

Disabling GitLab CI/CD in the GitLab UI is not a substitute for removing the file — the two systems can still conflict.

Self-managed instance connection problems

For GitLab self-managed 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 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. 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 or Set up a project section to create your project again, ensuring you complete all setup steps.

See also