Setting up a local GitLab and managing your git-repositories
A warm welcome to you at this article about GitLab. After reading this, you should have a basic understanding about the main functions of GitLab and get to know fundamental differences between GitLab and other systems to manage your git repositories.
There will be at least one follow-up article about using the provided continuous integration and continuous deployment possibilities of GitLab. So, keep your eyes open for more GitLab articles to come.
What is GitLab?
GitLab is a platform to manage your git-repositories. You can think of GitLab as an alternative to Github or Bitbucket or other services like these. I think this first sentence should give you a very good first impression of GitLab.
If you are a user of Github you will have high expectations on an alternative to it, but from my point of view, in some areas GitLab might have some advantages over other systems.
Why use GitLab?
You might ask yourself why I am thinking that way. GitLab offers three different versions.
There is the hosted version of GitLab, where you can register for free and you can create as many private and public repositories as you want to, that’s already a big advantage.
The second is the ‘GitLab Community Edition’, perfect for everybody who wants to know on which servers the code is located because you can operate the community edition on your own servers and it will cost you no money.
To me, that sounds really great but there’s is more to come. GitLab provides you the possibility to automatically test and deploy your code, all this with no extra money. On top of that GitLab got a large community behind the project that improves the software constantly.
The third and last version is the ‘GitLab Enterprise Edition’. It is based on top of the community edition and adds some extra features, it is mainly aimed at organizations with more than 100 users.
The Enterprise Edition will run on your own servers, too. For more information about the pricing and the differences between the versions checkout GitLab’s comparison.
But enough of me talking, let GitLab speak for itself in a practical introduction.
In this post I will show you how to install GitLab locally (in order to test it).
There are several ways to instal GitLab. I have decided to use Vagrant to install GitLab Community Edition, Vagrantfile to be specific. If you haven’t got Vagrant installed please check the official Vagrant installation guide.
So, let’s go. Open a text editor of your choice and insert the following lines of code or checkout the Vagrantfile from my GitLab repository.
(If you want to give the VM less than 4096 MB of RAM just change the value of vb.memory.)
# -*- mode: ruby -*- # vi: set ft=ruby : Vagrant.configure(2) do |config| config.vm.box = "ubuntu/trusty64" config.vm.network "forwarded_port", guest: 80, host: 8080 config.vm.network "private_network", ip: "192.168.33.10" config.vm.provider "virtualbox" do |vb| vb.memory = "4096" end config.vm.provision "shell", inline: <<-SHELL echo "apt-get update" sudo apt-get update echo "install curl openssh-server ca-certificates postfix" sudo apt-get install curl openssh-server ca-certificates postfix echo "get gitlab-ce script and run" curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash sudo apt-get update echo "install gitlab-ce" sudo apt-get install gitlab-ce sudo sed -i 's,external_url.*,external_url "https://192.168.33.10:80",g' /etc/gitlab/gitlab.rb echo "configure and start gitlab" sudo gitlab-ctl reconfigure SHELL end
After saving the file, open a terminal window, change to the directory where your Vagrantfile is located at and enter :
Now it’s time to wait a little bit. Maybe get yourself a coffee or tea ;-).
If everything worked fine, you should see something like
“==> default: gitlab Reconfigured!“
in your terminal.
Once this is done, browse to https://192.168.33.10 et voilà, GitLab is already running. Awesome, isn’t it?
The credentials to log in to your GitLab are:
In case these credentials are no longer working because GitLab changed them, please check out the GitLab Community Edition Download Page for the current password.
To improve security, GitLab will ask you for a new root password immediately after logging in for the first time.
After pressing “set new password“ you will be automatically logged out and you have to log in again with the password you have just set.
From here, we can really start using GitLab, so first we will add a new project, hit “+ new project“.
Then choose a name for your project and enter it into the last field of the project path.
The second option is if you want to import an existing git repo from one of the given providers or by entering the url of the git repository.
The third option is optional, you can decide for yourself if you want to enter a description or not.
Last but not least, choose a visibility level, there a three possibilities:
- Private means you have to grant project access explicitly to each user
- Internal means that the project can be cloned by any logged-in user
- Public means that the project can be cloned without any authentication of the user
So, make your decision and press “create Project“.
I will import the repository of our “simple_rails_app“ for this article.
Now we are already able to check out some nice features of GitLab, we can take a look at the commits section, here we got different choices we can make:
- Commits – to see a list of the commits of the chosen branch
- Network – to see a graph visualizing your repository
- Branches – to see a list of all your branches…
… and if you click „compare“ next to one of these branches you can see the differences between two branches, inline or side-by-side.
Next, there are also pretty fancy graphs (in the “Graphs“-section) you can have a look at if you want to.
A visualization of the contributors,
of the commits,
and the languages used.
Next steps will be creating a group, moving the project to this group, creating a new user and granting him the access to the project, so let’s do that.
To create a new group we have to navigate to the „Groups“-section on the left side, then click “+ New Group”, you should see an input mask similar to the one in the picture.
I will name our group graph “anynines” and enter an arbitrary description. If you want to you can also add a group avatar. After inserting all the information required, hit “Create Group”.
The following task is to transfer our private project to the group, in order to accomplish this, navigate to the “Projects”-section and choose your project.
In the upper right corner should be an icon with a pencil on it, please click that. Here, you can change the settings of your repository, if you scroll down a bit, there are several settings surrounded by a red border, these are the “dangerous” settings, be aware of that.
The box with “Transfer project” is exactly what we are looking for this time. If you click the dropdown field next to the namespace label you can choose to which namespace you want to transfer your project. In our case we will choose our just created group.
Choose “Transfer Project”. In the appearing window enter the name of your repository in the empty text field and “Confirm” your decision.
Let’s create a new user and add this user to our group, for this enter the admin panel via the “wrench”-icon in the upper right corner.
The admin area gives you a brief overview about your GitLab and you can create new projects, groups and users from here, which sounds like what we wanted to do.
Click “New User”, insert the information that is needed in the form and then “Create User”.
If you are using Gravatar you will get your Avatar right away, which is a nice feature.
This guy looks very friendly to me ( ;-) ), let’s add him to our group.
Once again, navigate to the “Groups”-section, choose your group and enter the “Members”-section.
In the field next to the word “People” you can search for the user you want to add.
Afterwards, choose a role for the user, it will decide which rights the user will have. You can find more information about the roles in the role permissions overview.
We will assign the role “Developer” to the user tester; with this role he can access the project files and work with them. After you enter all the information needed, press “Add Users To Group”.
At the bottom of the page you can see an overview about all members of the group with their roles and the possibility to remove them from group or edit their role.
So, what’s next on our to-do list? Creating a milestone in our project and then setting up an issue assigned to our recently generated user and linked to the milestone.
Back to our dashboard >> projects >> your project >> milestones, then click “+ New Milestone” and you should see an input mask similar to the one in the picture.
Add a title, a description and choose a due date, after that everything is ready to create the milestone.
With the “+ New Issue”-button we can add an issue to the milestone, so let’s do that. I entered all the required data, assigned the issue to our recently created user and added the issue to our milestone, “submit issue”.
The overview of the issue should look something like this.
There are just a few things left on our list: pushing a new branch with changes, opening a merge request for the branch and automatically closing the milestone and the issue by accepting the merge request. Then we will add continuous integration and continuous deployment as the last step.
In the meantime, I pushed a new branch with small changes to the repository, so let’s have a look if it is there and how to open a merge request for it. In the dashboard navigate to Projects >> your project >> commits >> branches there you can find the button “+ Merge Request”, go for it.
If you want to close some issues with a successful “merge request” you have to mention it in the title, e. g. “Fixes #1” or “Closes #1”. You can mention several issues in one title. Look at the GitLab Documentation for more information about the “issue closing pattern”.
The dashboard section “Merge Requests” is now showing you the number one right next to it, therefore go there and take a look at what we got there. Enter the new request; you can do several things like “closing” the merge request, “checking out” the branch or “accepting” the merge request. We will accept the request and mark the field for removing the source branch.
At the moment, there might sometimes be problems with the automatic issue closing, if you have them, have a look at this discussion perhaps this will help to solve your issue.
I think this should be enough for a first overview of GitLab. Perhaps you already explored some features or presentations of certain features that you like more than in your current system. In the next part I will show you how to get continuous integration and continuous deployment working. Stay tuned.