---
title: "Create a project in CircleCI"
description: "Create a project in CircleCI to give CircleCI access to the code in your repository, so it can check out that code and run pipelines against it."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-26"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Create a project in CircleCI

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 Server account. Your organizations are the GitHub organizations you belong to.
    
*   Code you want to build on CircleCI.
    

## Build a new project on CircleCI

On CircleCI Server, each project is a repository in one of your GitHub organizations. To build a repository on CircleCI, set it up as a project from the **Dashboard** in the web app and choose the configuration file to use. Follow the steps in [Set up a project](#set-up-a-project) below.

### Set up a project

Follow these steps to set up a new project in CircleCI:

1.  In the CircleCI web app, select **Dashboard** in the sidebar.
    
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](https://circleci.com/docs/guides/server/getting-started/config-intro/) 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 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.
    

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

## See also

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