GitLab is a complete, full-featured DevOps platform, which is built to create a streamlined toolchain and cover the entire lifecycle. Better yet, GitLab is open source, with thousands of contributors and users collaborating to make the software even better. By keeping everything together, you reduce overhead and save time. GitLab runs on Linux-based operating systems, and does not have a Windows version. The supported distributions are Ubuntu, Debian, CentOS, openSUSE, Red Hat Enterprise Linux, Scientific Linux and Oracle Linux. GitLab does not support macOS, although it is possible to install it with some work. A virtual machine is recommended if you don’t have a dedicated Linux box, although the latter is often preferable for speed.
Git repositories are used to store code versions, and you should have both a local repository and access to a remote one. Remote repositories are kept on the server, but local repositories need to be stored on your computer’s hard drive. In general, when creating a new project, you pull existing code from remote repositories, then create a local repository to store your changes so they don’t impact other users. This differs from GitHub, which expects all code to be stored remotely on their servers, and allows GitLab to be more secure. Otherwise, the two services tend to have similar functionality and it is possible to easily transfer code from one to the other.
So, how do you set up a local repository? This quick GitLab tutorial will tell you how.
Repositories versus Projects
The terms “repository” and “project” are sometimes used interchangeably. However, they are not quite the same thing. Each project has its own local repository, and you might pull from either a remote or an existing local repository when creating a project. Repository is also sometimes shortened to repo.
The project, however, also includes a description, the slugs that allow your project to be found by the GitLab instance, etc. However, there is only one repository per project which, again, leads to the terms often being used interchangeably. GitLab generally uses the term project, but we will be talking about repositories here as it is a more general term applicable to multiple systems, and thus understood by more people.
So, the first thing is to work out what kind of repository your project needs. The default in GitLab is to create a new repository. However, you can also clone (copy) a repository, or push an existing project to create a new one (which is a faster way of copying a local repository). By copying an existing repository, you are able to take working, functional code and quickly repurpose it for your new project, without altering the original. This might be your own code or open source code that you found on GitLab.
We’ll talk about all of these options in this article.
Creating a New Repository
Again, creating a new repository is the default. When you create a new project, Gitlab will automatically create a new, blank local repository. This repository can then be tied to a remote repository for collaboration purposes and can be protected using GitLab’s privacy settings.
Here are the steps:
- From your dashboard, click the green New project button.
- Choose whether to create a blank project or use a template.
- For a blank project:
- Fill in the name of your project in the Project name field. No special characters. This will automatically set the Project slug. You can also set the slug and have it generate the project name.
- Enter the project description, if you have one. This is optional, but useful for telling projects apart or reminding collaborators of their purpose.
- Set the project’s visibility level appropriately. Private means only you can see it, whilst public projects can be accessed by any GitLab user and cloned without authentication. Needless to say you don’t want to set your project to public unless you are working on something intended to be open source. The third option is Internal, which allows only users you authorize. (As a note, admin can disable setting projects public so that it does not happen by accident).
- Select the initialize repository with a README option, which will initialize the repository and set it up properly. It will also create a README file for the repository.
- Click create project.
- For a template:
- Click on the Create from template tab.
- Choose the built-in tab for built-in projects that come with GitHub, or the Instance or Group tabs for your own company’s projects. This can be helpful if you need to fork the same code several times or if you have standard code that you need in all of your projects.
- Look at the available list. The preview button will show you the source code itself, so that you can double check that you are using the right template.
- Click use template.
- Then fill out the project details as if you were creating a blank project and initialize the repository.
Again, once the project is created, the repository is also created. It’s that simple. You and your team can immediately get to work on developing your code. Make sure not to forget to initialize the project, or it simply will not work.
Creating a Project from a Cloned Repository
Generally, when you clone a repository, you are starting a project from a remote repository. You might discover there’s an existing, open source project on GitLab that does something close to what you need it to do. Or you might have something in your internal “stash” of code that is suitable for the project.
Rather than change the remote repository that’s shared with others, you need to make a local copy of it that you can work on. You can clone via https or ssh, but either way you need to open a terminal window in the directory you want to put the files in. The commands are similar, so make sure you use the one you have set up. GitLab generally recommends that you use https, which makes it more universally accessible, but if you are working with sensitive and proprietary code you should consider ssh, which can only be accessed if somebody has the key. Use either:
git clone email@example.com:gitlab-tests/sample-project.git
These commands can also be found by clicking Clone on your project’s landing page, which is a good way to make sure you get the path right. Regardless of which command you use, you will get a copy of the files that are named after the project and are still connected to the remote repository. However, this is still not a repository. You need to do one more thing. Go to the directory you just created in a terminal window and run
This command will create a .git file in your directory. Never edit these files directly, as that’s an easy way to break something in your code. You can also use cloning to create a local or internal archive of your code that is not initiated and thus will not be touched by GitLab even if somebody uses the wrong path.
You will then need to connect this directory to your remote repository by creating a new project following the instructions above. Once you have your new project, open its homepage and scroll down to Push an existing folder. You will find a command there that starts with git remote add.
Copy this command, open terminal in the directory you just initialized, and paste the command. This sets the path GitLab needs to keep your local and remote repositories connected and make sure everything is properly backed up. It’s easier to copy and paste these commands than try to generate them (and best not to try doing so from memory).
Note that you can work on stuff locally, but should always push (save) to the remote repository when you stop working and then download (pull) before starting again. This makes sure that everyone is on the same version of the files. If you are working on your own, it ensures that your work is backed up and won’t be lost if you have a problem with your local system. If you don’t change the remote repository, then it will stay linked by default to the master branch of the original remote repository; this may or may not be behavior you want. You can also add a new branch, allowing you to work on more experimental code safely, or work on two different ideas to see which one works better. These can later be merged back together to aid in collaboration and solidify your project’s path.
Creating a New Project by Pushing
Sometimes, you might want your new project to be a copy of one you are already working on. Templates can help with this, but templates are intended for bringing in a few items of standard code, rather than copying the entire project. Another way to achieve this is to clone the repository locally.
However, GitLab provides a third, much easier way to do this. Again, you can use either SSH or HTTPS to do this from within terminal. Here are the commands:
Git push using SSH git push — set-upstream
Git push using HTTPS git push — set-upstream
Obviously you should replace namespace with your namespace, and nonexistent-project with the name of your new project.
This will create a new project in that namespace, visibility set to Private. You can navigate to the homepage and adjust the visibility, then start working.
This is much faster than going through the extra steps of creating a project then adding a repository to it. You can also push git repositories that were created using other systems. This is useful if you are changing systems or if you acquire code from another source, such as Github, which we will use as the example here.
Here are the steps:
- Create a new directory.
- git clone — mirror https://github.com/namespace/project
- cd project.git
- git remote add gitlab https://gitlab.example.com/namespace/project.git
- git push gitlab — mirror
This will essentially import your existing local repository into GitLab. Again, this is useful if you are changing your git systems or using open source code that you are taking from somewhere else. It’s often worth checking publicly available code on GitHub to see if there is anything that will serve your purposes, although you should look on GitLab first for ease of transfer.
You can then work with the project as normal. Again, these projects will default to Private visibility. Remember that the command git init is always used to initialize a repository; if things are not working the way you expect, try using that and then trying again. Also use git commit to make sure that the files are part of the repository. Some tools call this “staging” the files. The git commit command tells the repository which pieces of code are part of the project, so that unfinished code is not called.
So, this is how you set up your local repositories correctly with GitLab. GitLab allows for much more flexibility than GitHub as to where you can save your files, but still gives you plenty of open source code that you can add to your project as needed.
Learning all of the features of GitLab is a challenge. Our GitLab bootcamp is a two day course that can be taken in person or online (right now, because of the public health situation, we are only offering online courses. It includes practical scenarios to allow you to learn all of the features of GitLab and gives you access to experts who can help you understand how to best apply it to your business. And yes, that includes properly setting up local git repositories and committing changes, as well as how to use GitLab’s powerful collaboration and security features. We can also arrange for internal corporate training for your entire team, as well as individual training for upskilling or onboarding.
To find out more about our GitLab bootcamp and other training options, contact Cprime today.