GitLab - Create Project

GitLab - Creating a New Project

This chapter guides you through creating a new project in GitLab and making your first push. GitLab projects are the core of your development work, housing your code, issues, CI/CD pipelines, and more.

Creating a Project via the GitLab UI

Step 1: Log in to your GitLab account. On your dashboard or by clicking the ’+’ icon in the top navigation bar, select ‘New project/repository’.

Step 2: You’ll be presented with several options for creating your project:

Create blank project: Start with an empty project. You’ll define the project name, an optional description, its visibility level (Private, Internal, or Public), and can choose to initialize it with a README file.
Create from template: GitLab offers built-in templates for various project types (e.g., Ruby on Rails, Spring, NodeJS Express) or you can use instance-level or group-level custom templates if configured.
Import project: Migrate an existing project from other platforms like GitHub, Bitbucket, or by uploading a Git repository URL.
Run CI/CD for external repository: Connect an external repository (e.g., from GitHub) to GitLab for CI/CD purposes without fully migrating the codebase.

Step 3: For a new blank project, provide the following details:

Project name: A descriptive name for your project.
Project slug (Optional): The URL-friendly path for your project. GitLab usually generates this from the project name.
Project description (Optional but recommended): A brief overview of your project.
Visibility Level:
- Private: Only project members can see and access the project.
- Internal: Any logged-in user on your GitLab instance can see and access the project (not applicable to GitLab.com unless you are part of an organization).
- Public: The project is accessible to anyone, even without a GitLab account.
Initialize repository with a README (Recommended): This creates an initial commit with a README.md file, making it easier to clone the project immediately.

Click ‘Create project’. GitLab will then set up your new project repository.

Pushing an Existing Local Repository to Your GitLab Project

If you’ve created a blank project in GitLab (without initializing with a README) and you have an existing local Git repository, you can push it to GitLab. If your project in GitLab was initialized with a README, you should first clone it, add your files, commit, and then push.

Assuming you have a local repository and an empty GitLab project:

Step 1: Navigate to your local repository’s directory in your terminal or command prompt.

cd /path/to/your/local-repo

Step 2: Add the GitLab repository as a remote. You can find the repository URL (HTTPS or SSH) on your GitLab project’s main page, under the ‘Clone’ button.

# Using HTTPS
git remote add origin https://gitlab.example.com/your-username/your-project-name.git

# Or using SSH
git remote add origin git@gitlab.example.com:your-username/your-project-name.git

Step 3: Push your local repository’s branches to GitLab. If your local main branch is named master and GitLab’s default is main (or vice-versa), you might need to rename it or push specifically.

# Push all branches and tags
git push -u origin --all
git push -u origin --tags

The -u flag sets the upstream remote for your current branch, so future git pull and git push commands can be run without specifying origin main.

Cloning and Pushing a New Local Repository to GitLab

If you started by initializing your GitLab project with a README, or if you want to start fresh locally:

Step 1: Clone the repository to your local system. Get the clone URL (HTTPS or SSH) from your GitLab project page.

# Using HTTPS
git clone https://gitlab.example.com/your-username/your-project-name.git

# Or using SSH
git clone git@gitlab.example.com:your-username/your-project-name.git

cd your-project-name

Step 2: Create or add your project files. For instance, create a README.md if it doesn’t exist, or add your application code.

echo "# My New Project" >> README.md
# Or copy your existing project files here

Step 3: Add the new files to Git’s staging area.

git add .  # Adds all new and modified files
# Or git add README.md specific_file.py

Step 4: Commit your changes with a descriptive message.

git commit -m "Initial commit with project setup"

The -m flag is for the commit message.

Step 5: Push your commits to the remote repository on GitLab. If your local branch is named main (which is the modern default), and you cloned the project, the remote origin and upstream branch should already be set.

git push origin main  # Or 'master' if that's your branch name

After pushing, refresh your project page on GitLab. You should see your files and commit history.

Best Practice: Default Branch Name

Modern Git workflows, including GitLab’s default, use main as the default branch name instead of master. If your local Git configuration still defaults to master, you can change it globally or per project. GitLab allows you to configure the default branch name for new projects within your group or instance settings.