Creating projects

Most work in GitLab is done within a Project. Files and code are saved in projects, and most features are used within the scope of projects.

Create a project in GitLab

To create a project in GitLab:

1. In your dashboard, click the green New project button or use the plus icon in the navigation bar. This opens the New project page.
2. On the New project page, choose if you want to:
   • Create a blank project.
   • Create a project using with one of the available project templates.
   • Import a project from a different repository, if enabled on your GitLab instance. Contact your GitLab admin if this is unavailable.
   • Run CI/CD pipelines for external repositories. (PREMIUM)

NOTE: Note: For a list of words that cannot be used as project names see Reserved project and group names.

Blank projects

To create a new blank project on the New project page:

1. On the Blank project tab, provide the following information:
   • The name of your project in the Project name field. You can't use special characters, but you can use spaces, hyphens, underscores or even emoji.
   • The Project description (optional) field enables you to enter a description for your project's dashboard, which will help others understand what your project is about. Though it's not required, it's a good idea to fill this in.
   • Changing the Visibility Level modifies the project's viewing and access rights for users.
   • Selecting the Initialize repository with a README option creates a README file so that the Git repository is initialized, has a default branch, and can be cloned.
2. Click Create project.

Project templates

Project templates can pre-populate a new project with the necessary files to get you started quickly.

There are two types of project templates:

• Built-in templates, sourced from the following groups:
  • project-templates
  • pages
• Custom project templates, for custom templates configured by GitLab administrators and users.

Built-in templates

Built-in templates are project templates that are:

• Developed and maintained in the project-templates and pages groups.
• Released with GitLab.

To use a built-in template on the New project page:

1. On the Create from template tab, select the Built-in tab.
2. From the list of available built-in templates, click the:
   • Preview button to look at the template source itself.
   • Use template button to start creating the project.
3. Finish creating the project by filling out the project's details. The process is the same as creating a blank project.

TIP: Tip: You can improve the existing built-in templates or contribute new ones in the project-templates and pages groups.

Custom project templates (PREMIUM)

Introduced in GitLab Premium 11.2.

Creating new projects based on custom project templates is a convenient option to bootstrap a project.

Custom projects are available at the instance-level from the Instance tab, or at the group-level from the Group tab, under the Create from template tab.

To use a custom project template on the New project page:

1. On the Create from template tab, select the Instance tab or the Group tab.
2. From the list of available custom templates, click the:
   • Preview button to look at the template source itself.
   • Use template button to start creating the project.
3. Finish creating the project by filling out the project's details. The process is the same as creating a blank project.

Push to create a new project

Introduced in GitLab 10.5.

When you create a new repository locally, instead of going to GitLab to manually create a new project and then clone the repo locally, you can directly push it to GitLab to create the new project, all without leaving your terminal. If you have access rights to the associated namespace, GitLab will automatically create a new project under that GitLab namespace with its visibility set to Private by default (you can later change it in the project's settings).

This can be done by using either SSH or HTTPS:

## Git push using SSH
git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master

## Git push using HTTPS
git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master

Once the push finishes successfully, a remote message will indicate the command to set the remote and the URL to the new project:

remote:
remote: The private project namespace/nonexistent-project was created.
remote:
remote: To configure the remote, run:
remote:   git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git
remote:
remote: To view the project, visit:
remote:   https://gitlab.example.com/namespace/nonexistent-project
remote: