GitLab Projects

Last updated on 2022-05-06 | Edit this page



  • How can I use GitLab to manage my project’s files?


  • Create a project.
  • Change name, description, visibility, and avatar of a project.
  • Push a local Git repository to a newly created project.
  • Archive (or delete) a project.

Creating a Project

After knowing how to find groups and projects. We want to go from passively browsing GitLab to actively using it. We are going to create a project and connect a local Git repository to it.

To create a project, click on the button with the “+” symbol in the top menu bar and select “New project/repository”.

Multiple options are presented for how to create the new project. In this lesson we will only look at, and use, the first option: “Create blank project”. So click on that.

This leads to the following page:

Create blank project form with text input fields labeled “Project name”, “Project URL”, “Project slug”, “Project description (optional)”, “Project deployment target (optional)”, a radio button element labeled “Visibility Level” with options “Private” and “Public”, and two checkboxes labeled “Initialize repository with a README” and “Enable Static Application Security Testing (SAST)”.
Create blank project form

The “Project name” field is for just that, the project name. Its value has no other purpose and can be changed at anytime without indirect consequences (the direct consequence being, that its name will be different). We will call it “Research Diary”.

As we fill in the project name, a project slug gets suggested in the respective field. The project slug is the last part of the project’s, and the associated Git repository’s, URL or web address.

If the user belongs to at least one group, the URL’s middle part can be chosen in the drop-down field labeled “Project URL”, which defaults to the current user’s username. This is the location for a user’s project (and groups). Other options in the drop-down list are the groups in which the current user may create projects.

Project URL and Project Slug

The two fields under labels “Project URL” and “Project slug” are the only fields in this form for which changing the value later might cause problems. Since they determine the URL under which the project’s pages and the project’s Git repository can be found, changing them later might brake links and bookmarks as well as connections from Git repositories on other systems, for example on contributors’ machines.

The project description appears in many lists and on some pages under the project’s name. We add a concise description: “My research diary, a collection of Markdown files”


Markdown is a markup language, like HTML on which the World Wide Web is based or wikitext used to write Wikipedia’s content. Its markup directives, indicating for example that something is a headline or a list item, are such that they serve their purpose even in the plain text form.

There exist many variants (or flavors) of Markdown and GitLab has its own. Other than for rendering Markdown files in repositories on its web interface, GitLab allows for Markdown input in many of its interface’s text fields, such as issue descriptions or comments.

This will be pointed out as we get to use these fields during the lesson.

We ignore the field labeled “Project deployment target (optional)”.

The choice of radio button under label “Visibility Level” determines the project’s visibility. As mentioned in the previous episode “Finding Projects and Groups”, the visibility “Internal” is disabled on, so only “Private”, the default, and “Public” are available. We choose “Private”.

If, as per default, the checkbox “Initialize repository with a README” is checked, the project’s repository will be initialized with a commit that adds a file called Otherwise, a the project will start with an empty repository. We will be adding such a file later ourselves, so we uncheck the box.


A project’s README file usually contains basic information about the project: what it contains, how it can be used (for example build or installed, if it is a software project), how to contribute, how to get help, and licensing information.

It is common to write README files in Markdown format, indicated by the filename suffix .md.

Platforms like GitLab show the contents of a project’s README file on its homepage; if it is in Markdown format, in its rendered form.

We will ignore any other fields that may be visible depending on the GitLab instances configuration.

After clicking the “Create project” button, GitLab creates the project and redirects us to the project’s homepage, which looks similar to this:

Project homepage for a new project. On the left, a menu leading to other project pages: Project Information, Issues, Merge requests, CI/CD, Security & Compliance, Deployments, Monitor, Infrastructure, Packages & Registries, Analytics, Wiki, Snippets, and Settings. On the right, taking up the major part of the width, the project page: Starting at the top, the project’s name “Research Diary“, followed by its descriptions “My research diary, a collection of Markdown files”, an encouragement to “Invite your team” with a button “Invite members”, the statement that “The repository for this project is empty” with various buttons for getting initial content into the repository. At the bottom, the beginning of instructions on how to push an existing repository are visible, but cut off.
Fresh project homepage

The page is split into the menu on the left and the project overview on the right.

The menu leads to pages related to various properties, processes, and content of the project. It is visible on each of these pages. The number of menu entries may seem overwhelming, in particular when one notices that the entries have subentries. However, it is not necessary to know what hides behind all these entries to use GitLab. Following this lesson, we will get to know parts of what lies behind the entries “Project Information”, “Issues”, “Merge requests”, “CI/CD”, “Wiki”, and “Settings”.

The project overview shows (from the top): The project’s avatar (or icon), name and description; a prompt to invite team members (we will cover members later on); a statement that our repository is currently empty with buttons for several options to add content to it; and finally the beginning of the instructions on how to push a local repository to this project’s repository to fill it with content. We will follow them in just a bit.

The project overview page will look slightly different, once we have content in its repository. We will have another look at the page then.

Change Name, Description, Visibility, or Avatar

Click on the “Settings” menu entry and change any of the project’s name, description, visibility, and avatar. Do not forget to click the “Save changes” button once you are done.

This exercise should take about 5 minutes.

The project overview page presents us with many options to add content to the project’s repository directly in GitLab. However, we will fill the project from a local Git repository. To do that, we need a local Git repository with some content.

Configuring Git

Before we initialize a local Git repository, we make sure that Git is properly configured.

To check for our name and email address, We run

$ git config --global --get

{: .language-bash}


$ git config --global --get

{: .language-bash}

If both return sensible values, we are good to go. Otherwise we provide the missing values, for example:

$ git config --global "Some Novice"
$ git config --global ""

{: .language-bash}

It is now common to name the default branch main, rather than master as is still the default in Git. For more information see, for example, the announcement of GitLab to change the default branch Since the discussion on this topic has started, Git has introduced a configuration value for the initial branch created by the git init command. We will use this, to make sure that all future repositories created locally start with a branch called main:

$ git config --global init.defaultBranch main

Creating a Local Repository

Markdown Headlines

In Markdown, headlines are marked by one up to six # characters followed by a space character in front of the text. The number of # characters indicates the heading’s level, with 1 being the most significant.

For example, a level 3 headline:

### Interesting Section Title

Research Diary’s Initial Content (Required)

Create a Git repository anywhere on your computer. Add a README file in markdown format that describes the repository’s future contents.

Remember to use a good commit message for your commit.

This exercise should take about 10 minutes.

We start by creating and navigating to a new directory, research-diary. There we initialize a git repository.

$ mkdir research-diary
$ cd research-diary
$ git init

Next we create a file called with the following content using our preferred text editor.

# Research Diary

This repository contains our research diary.
Each day gets its own file.
We use the Markdown format for our files.

Finally, we stage the added file using and create a commit.

$ git add
$ git commit -m "Add"

Checking the status of the git repository, we should see that it exists and that there are no changes in the working directory or in the stating area:

$ git status

{: .language-bash}

On branch main
nothing to commit, working tree clean

{: .output}

There is one file,

$ ls

{: .language-bash}

{: .output}

Connecting Local and Remote Repository

Having thus created our local repository, we want to save it to our repository in GitLab. To that end, we have a look at the project overview page again; this time at the instructions toward the bottom of the page. They read:

Git global setup

git config --global "Some Novice"
git config --global ""

Create a new repository

git clone
cd test
git switch -c main
git add
git commit -m "add README"
git push -u origin main

Push an existing folder

cd existing_folder
git init --initial-branch=main
git remote add origin
git add .
git commit -m "Initial commit"
git push -u origin main

Push an existing Git repository

cd existing_repo
git remote rename origin old-origin
git remote add origin
git push -u origin --all
git push -u origin --tags

We already covered the global setup.

The next three sets of instructions are mutually exclusive. The first is not for us, because we already created a repository. Neither is the second, because although we have a directory with contents, its already a Git repository. That leaves us with the third option, which is the one applicable to our situation: “Push an existing Git repository.”

Transferring our changes to a remote repository is called pushing, because we are sending the changes from us, the local repository, to somewhere else, a remote repository. Later on we will “pull” changes from a remote repository, completing the analogy.

Going back to the shell, we configure our project’s repository as a remote in our local repository:

$ git remote add origin

{: .language-bash}

https:// vs git@

We assume throughout this lesson that the user has no SSH key is configured, because we do not want to make the setup of such a key a prerequisite.

If however, a user has configured an SSH key for their account, GitLab would default to showing links to repositories in the form for Git over SSH instead.

For example, without a configured key GitLab shows

for our example repository, whereas with a configured key it would show

The HTTPS link still works if a SSH key is configured, it is only no longer shown by default.

We instruct Git to add a remote called origin with the last part as the address. Make sure to copy that last part from the project overview page, because it represents the Git address of your project’s repository on GitLab. It will be different for everyone.

Note also, that we skipped the second line of the instructions. It renames an existing remote origin to old-origin, but we have no existing remote.

Names for remotes

Apart from following restrictions that Git puts on remote names, which can be avoided without much thought by using only letters, numbers, underscores, and hyphens, we should choose meaningful names for remotes, in particular, when we add multiple remotes to a local repository.

In most examples, origin is used as the name for a remote, because it is the name of the remote created when cloning a repository. It is a meaningful name for the main remote repository, if there is one. This together with its ubiquitous use make it a very good name.

In other cases, we might call a remote to a private copy of the main repository after our username or server it is located on, for example uni for a university GitLab instance.

Finally, we push our changes to the remote repository. The command will prompt for our user name and password:

$ git push -u origin --all

{: .language-bash}

Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 250 bytes | 250.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

{: .output}

Having successfully pushed our commit to the GitLab repository, we change to our browser and navigate to the project (or reload it, if we still have it open). We will be greeted by the project homepage, similar to the following screenshot:

Project homepage of a project. On the left, a menu leading to other project pages. On the right, taking up most of the width, the project homepage. Starting from the top, we first have the project title, Research Diary, followed by a line of statistical values (1 Commit, 1 Branch, 0 Tags, 72KB files, 72 KB Storage). Under these we see the description: “My research diary, a collection of Markdown files”. In the next line we see a drop-down field for branches showing “main”, the project slug¸“test”, a drop-down button labeled “+”, and buttons labeled “History”, “Find file”, “Web IDE”, a download symbol, and ”Clone”. This is followed by a box giving information on the last commit of the current branch: the commit message “Add”, the authors name and how far in the past the commit was authored, as well as prefix of the commit’s hash with a copy-to-clipboard button. This is followed by some buttons that allow to add or upload new files or setup some of GitLab features for the project. Next is a list of files, in this case only ``, with information when it was last updated and through which commit. Finally, we see a rendering of ``.
Project homepage after first push

Let us look at what has changed compared to its initial state. The interface elements encouraging us to add members to the project are gone. Of course, we can still navigate to the project’s Members later on, if we need to. We also, correctly, no longer get told that the repository is empty and the instructions on how to push content to the repository have vanished.

Instead, we see some statistics below the project’s title: 1 Commit, 1 Branch, 0 Tags, 72 KB Files, 72 KB Storage. They double as buttons other project pages.

Below the description is a new button bar, followed by a box presenting information on last commit of the currently select branch.

The buttons below, that we saw earlier, allow us to add specific files or navigate to the configuration of certain GitLab features. Note that one button changed from reading “Add README” to just “README”, since we added The button is now a link to the latest version of that file in the current branch.

Then we see a list of files. So far, there is only The list also tells us through which commit it was last changed and when that commit was created.

Finally, we see the markdown file rendered. Because having a README-file in the root directory of a repository is a widespread convention, GitLab (and other platforms like it) usually render it on a project’s homepage.

Archiving a Project

We just went through the beginning of a GitLab project’s life cycle. At its end, if it has one, a project gets archived (or deleted). We will now go through the process of archiving a project, without completing the step.

Using the menu on the left, we navigate to the projects settings.

At the bottom the page, we find a section named “Advanced”. We hit the “Expand” button right next to it and scroll down the page.

Notice that many of buttons here are not the usual blue or white, but after scrolling a little they are red. This indicates that we should be careful about clicking them. Things might break or get deleted.

Scrolling back up, we find a section labeled “Archive Project”. Clicking the button will not delete the project. Instead it will be placed in a read-only mode. Everything will be preserved but nothing can be changed anymore. In addition, the project no longer shows up in search results and on the page for exploring projects.

Most of the time archiving a project is preferable to deleting it, in particular when it comes to research projects. Do not archive the project now! We will work with it throughout this lesson.

At the bottom of the page is also a section for deleting a project, in case you ever think that is the right thing to do.


  • Creating a GitLab project requires not more than a few clicks and providing a name.
  • Changing the name of description of a GitLab project after creation has no indirect consequences.
  • You can fill a fresh GitLab project’s repository by pushing a local repository.
  • You can archive a project (and you can delete a project, but often should not.)