Installing GitLab

To take advantage of the administrative functions covered in the remainder of this chapter, you should create a local instance of GitLab so that you can log in as the Administrative account holder. This chapter covers the Community Edition, not the Enterprise Edition of GitLab. The Enterprise Edition is available for a fee and includes additional functionality, such as JIRA integration. You can read about the differences at the feature comparison list.

The recommended way to install GitLab is through one of its Omnibus installer packages. These packages can be downloaded directly and placed onto a Linux server, or can be deployed via a one-click install on some provisioning services.

DigitalOcean offers a one-click install package for GitLab. This package uses the Omnibus installer for GitLab, which means you will be able to upgrade GitLab easily if there are new features or security releases. At the time this was written, DigitalOcean was the only service offering a one-click installer for the Omnibus package. Bitnami and the AWS marketplace only offered deployments from source packages, which cannot be upgraded once deployed. Read the descriptions carefully to ensure you are not getting trapped into installing only a specific version.

To avoid the hosting fees while evaluating GitLab, you can also install it locally using the power of virtual machines. (It’s not as scary as it sounds.) Virtualbox and Vagrant are the easiest way that I have found to set up a Linux server on my Windows and OS X computers. The written documentation for Vagrant is phenomenal; however, if you prefer hands-on videos, I did put together a video series for a slightly older version of Vagrant. The basics haven’t changed.

Loosely, the steps are as follows:

1. Install Virtalbox.

2. Install Vagrant.

If you are on OS X, there is already a brew recipe for Virtualbox and Vagrant; it is appropriate to use it.

With those two packages installed, you now have the capacity to have an Ubuntu server running on your local machine. The virtual machine will not have GitLab installed, though. At this point, you could install GitLab using the Omnibus package referenced previously, but I found the following GitLab Installer really straightforward to use.

At the command line, complete the following steps:

1. Clone the installer project from GitHub:

$ git clone https://github.com/tuminoid/gitlab-installer.git

2. Inside the project repository, change the name of the Ruby configuration file from gitlab.rb.example to gitlab.rb.

3. Start the virtual machine:

$ vagrant up

The new virtual machine will be provisioned. The username and password will be printed at the end of the startup message from Vagrant. If you can’t remember it, or have closed the window, the information is also available at the end of the install script.

Regardless of the installation method you choose, you will need to be able to log in as an administrator on your new GitLab instance to take advantage of the remainder of this chapter. Once you have logged in, you should be redirected to the welcome screen shown in Figure 12-1.

Figure 12-1. The welcome screen for GitLab

If you aren’t able to complete the installation, I encourage you to skim through the rest of the chapter to see what would have been available to you so that you can verify if it’s worth the effort to get it figured out.

Configuring the Administrative Account

You may choose to keep the admin account generic, or use it as your own account when developing software with your team. Out of habit, I tend to create an account with fewer privileges for daily use and maintain the root account for tasks such as installing new add-ons, upgrading the software, and other administrative tasks.

To configure your account, complete the following steps:

1. From the top menu, locate and click the icon profile settings (head and shoulders of a person).

2. From the left sidebar, review each of the profile settings pages:

   Profile

   Name, and public details about yourself, such as Skype or Twitter.

   Account

   Private token, Two Factor Authentication, Username, and the ability to delete your account.

   Applications

   Manage applications that can use GitLab as an OAuth provider, and applications that you’ve authorized to use your account.

   Emails

   Primary email (avatar, commit credits), notification email, public email (displayed email). Any of these addresses can be used to connect a commit to you.

   Password

   Reset your password.

   Notifications

   Your notification email as well as your notification level. By default, you will only receive emails for related resources (your commits, your assets, etc). You may also choose from Watch (all notifications for a given project); Mention (only when you are @referenced on an issue or comment); or Disabled (never receive a notification).

   SSH Keys

   Note: you will not be able to work with repositories over SSH unless you are logged in to an account with SSH keys. A reminder will appear until it is dismissed, or your SSH keys are uploaded.

   Design

   Color settings for the sidebar, and code syntax highlighting.

   History

   All events created by this account. Includes actions you’ve taken such as commits, creating new projects, etc.

Once you’ve configured the administrative account, you are ready to proceed. If you decide to set up a secondary account immediately, jump ahead to “User Accounts”.

Administrative Dashboard

When logged in as the administrative user, you will have access to some additional screens, and functions that are not available to nonadministrators on the public GitLab.com site. Most of these are available from the Admin area.

From the top menu, click the gear icon labeled Admin area. You will be redirected to the page shown in Figure 12-2.

Figure 12-2. The administrative dashboard includes a summary of site details, and a status report showing which version of GitLab is installed

This screen gives a summary of the components installed for this instance of GitLab, including the software version you have installed for GitLab, GitLab shell, GitLab API, Ruby, and Rails. There is also a list of all available features, with a status indicator showing which ones are enabled. In Figure 12-2, you can see that Sign up and Gravatar are enabled; LDAP and OmniAuth are disabled. Gloriously, they do not rely on color alone. The closed circle is green to indicate “on”; the “off” symbol is the icon for standby. Unfortunately these symbols are provided by CSS alone, and there does not currently appear to be a text equivalent.

Each of the options down the left sidebar are fairly self-explanatory:

Overview

This is the screen you see in Figure 12-2. Provides a quick overview of stats for the site, along with quick links to create new users, projects, and groups.

Projects

Search for projects within the site, including filters for per-user, in-active (no activity in the last 6 months), and visibility level (private, internal, or public).

Users

Search for accounts within the site. Includes fitlers for administrators, blocked accounts, and people without projects.

Groups

Search by name for groups or add a new group. There are no filters available for this screen.

Deploy keys

A list of all keys that are being used for deployments; you can also add new ones from this screen.

Logs

The last 2,000 lines for each of githost.log, application.log, production.log, and sidekiq.log.

Messages

The ability to add a timed broadcast message to all system accounts. Useful for scheduled maintenance, recent upgrades, and more.

System hooks

A list of all existing system hooks. From the list of hooks, you can test a hook or remove it. You can also add new hooks (URLs) at this screen.

Background jobs

A summary of background jobs running in sidekiq.

System OAuth applications

A list of existing applications, and the ability to add new ones (fields for a title, and redirect URIs).

Service templates

Service templates allow you to set default values for project services. Depending on the service, different configuration options are available. For example, external services such as Asana and Buildkite have fields for API keys. Some services, such as JIRA and Redmine also have configuration fields (Project URL, Issues URL, New Issue URL). Some services, such as Emails on push, also have toggles for the triggers (push events versus tag push events). This is a good screen to skim through if you want to integrate with third-party services.

Application settings

Includes settings for default project settings and site-wide configuration options.

To lock down your instance of GitLab, you will need to use several of the options on the Application settings screen. The settings on GitLab are fairly liberal. By default, the application is open to new registrants, who are restricted to 10 repositories, but the default setting for a new repository is private.

The Features section includes the following settings (all are enabled by default):

Signup

Allow people to create accounts.

Signin

Allow people to authenticate themselves. If you wanted a read-only public repository, it would be appropriate to use this option.

Gravatar

Integration for user profile pictures—needs a connection to the Internet.

Twitter

Show users a button to share their newly created public or internal projects on Twitter.

Version check enabled

Checks to see if a newer version of GitLab is available.

Visibility and access control includes the following settings:

Default branch protection

Options are:

• Not protected (developers and “masters” can push commits; delete branches; and force push new commits to a branch)
• Partially protected (developers can only push new commits; masters can make any changes)
• Fully protected (only “masters” can make changes to the repository).

  By default, Fully Protected is selected.

Default project visibility

Options are:

• Private (project access must be granted explicitly for each user.)
• Internal (the project can be cloned by any logged-in user.)
• Public (the project can be cloned without any authentication).

  Private is selected by default.

Default snippet visibility

Options are Private, Internal, or Public. Private is selected by default.

Restricted visibility levels

Selected levels cannot be used by nonadmin users for projects or snippets.

Restricted domains for sign-ups

Only allow accounts to be created by those who hold email accounts for the selected domain names. Wildcards are allowed.

There are limit settings:

Default projects limit

By default, each account is only permitted to have 10 repositories; this includes the private forks a developer may need to submit a merge request to a project. If developers are working on several internal projects at once, this number might need to be increased.

Maximum attachment size (MB)

By default, this is set to 10MB. This should be sufficient for most screenshots, but may not be high enough if you are also attaching design assets to issues.

And finally, sign-in restrictions:

Home page URL

The URL people should be redirected to when they visit any page other than the sign-in page as a nonauthenticated user. If left unset, people will be redirected to the sign-in page.

Sign in text

This text appears on the sign-in page, below the description of GitLab. You should begin with a heading to separate your text from the GitLab description.

By configuring each of these settings, you can create an appropriate starting point for your instance of GitLab. For example, if you wanted to make it for official work only by approved individuals, you might adjust the settings as follows:

• Disable the signup feature.

• Disable the Twitter feature (removes the button from the interface that encourages tweeting about projects).

• Set the Restricted visibility levels so that public repositories and snippets are disabled (sign-in will be required to view all repositories).

If you wanted to make your instance a bit more open, you might adjust the settings as follows:

• Enable the signup feature.

• Disable the Twitter feature.

• Disable public repositories for nonadmins.

• Restrict domains for signups to your organization.

In addition to these settings, you can further customize the setup of each project to suit your needs.

Creating a Project

A project is effectively a repository with the accompanying support tools such as issue queues and wiki pages. When creating a new project in GitLab, you will have the option to import from GitHub, Bitbucket, Gitorious, Google Code, or any other repository that is available to your GitLab instance via a URL.

To create a new project, complete the following steps:

1. From the top menu, locate and click the icon New repository. This is a +. You will be redirected to the project creation form.

2. Complete each of the fields for the new project as shown in Figure 12-3:

   Project path

   This will be the URL for your project page. Use lowercase letters and hyphens only.

   Namespace

   The name of the account, or group, this project should belong to. By default, your own account is selected.

   Import project from

   If the project already exists, you can import it from one of the listed services. GitLab must have access to the service in order to complete the import—in other words, you can’t be behind a firewall without access to the Internet; and you will need to enable OAuth access to the project. The instructions in the pop-up window (Figure 12-4) will take you to the relevant documentation page for the service you want to connect to.

   Description

   Information about your project to be used in listings. This is not a complete README.

   Visibility Level

   Choose between Private (only visible to authorized users), Internal (visible to all logged in users), or Public (visible to anyone visiting the site).

3. Locate and click the button Create project.

Your new project will be created. If you have selected the option to import from an external service, the repository, issues, and wiki pages will be imported if supported. You will be redirected to the new project page.

With the project imported, you are now able to add administrators and developers to the project.

Creating User Accounts

To create a new user account, you can begin from a number of different places. The easiest to access is via the Admin area overview:

1. From the top right, click the gear icon labeled Admin area. You will be redirected to the admin area overview page.

2. Locate and click the button New user. You will be redirected to the new user creation form.

The form, as shown in Figure 12-5, is divided into three sections: Account, Access, and Profile.

The fields in the Account section are all required:

Name

Display name for this account.

Username

Login name for the account.

Email

The email address for this account.

The default values for the Access details fields are typically appropriate:

Project limit

The default quantity is whatever you have previously set site-wide. GitLab ships with a default of 10.

Can create group

The ability to cluster projects. This functionality is referred to as a team or organization in other systems. This is enabled by default.

Admin

Allow this person to administer the GitLab software. This is disabled by default.

Finally, there is the Profile section, which includes a field to upload a photo and social media links:

• Avatar—if Gravatar is enabled, it may not be necessary to include a separate user profile picture

• Skype

• LinkedIn

• Twitter

• Website

Although you can take the time to fill in the Profile details, not all employees will want to link their social media accounts to a work system. It may be more appropriate to leave them blank.

To create a user account, complete the following steps:

1. Fill in the Account details as described previously.

2. Confirm the Access details are correct.

3. Review the Profile details to ensure they should be left blank. Fill in any details that are appropriate to add now.

4. Locate and click the button Create user.

Figure 12-5. The new user account creation form is divided into three sections: Account (required fields), Access, and Profile

The new user account has been created; and a notification email has been sent to the person with a one-time login link she can use to set up her password.

In addition to this manual account creation, GitLab also offers LDAP and OmniAuth integration. Setting up this type of access is covered in the GitLab documentation. As of the time of this writing, supported OmniAuth providers included GitHub, Twitter, and Google.

Adding People to Projects

To add people to a project, complete the following steps:

1. Navigate to the project page.

2. From the sidebar, locate and click Settings.

3. From the left sidebar, locate and click Members.

4. Locate and click Add members. A new form will open (Figure 12-6).

5. In the field labeled People, enter the username or email of the person you want to add to this project.

6. Adjust the field labeled Project Access to one of the following:

   Guest

   Able to view the project, create issues, leave comments

   Reporter

   Able to clone the repository, create code snippets

   Developer

   Able to commit code to approved branches

   Master

   Project administrator

   Owner

   Able to remove the project

7. Locate and click Add users to project.

The accounts have been granted appropriate access to your new project. If the email was not already registered in this instance of GitLab, an invitation will have been sent, asking that person to register.

Adding People to Groups

Permissions are set primarily on the projects, not the groups. There are, however, some additional actions that users can take if they are granted group-specific roles:

• Everyone is able to browse the group.

• Only the Owner is allowed to edit the group, manage the group’s members, and remove the group.

• Group Masters are also able to create projects within group.

To add a person to a group and assign a role to the person, complete the following steps:

1. From the top menu, click the gear icon for the Admin area.

2. From the left sidebar, click the menu link Groups. You will be redirected to the Group administrative page.

3. Locate the form to add a user to the group (Figure 12-8).

4. Enter the details for each user you want to add to the group:

   Username

   You can add multiple people with the same role (Figure 12-9).

   Role

   Choose one of Guest, Reporter, Developer, Master, or Owner.

5. Click Add users to group.

Figure 12-8. Add a user to a group

The group will not be visible until there is at least one project added to it.

Adding Projects to Groups

Adding a project to a group is a simple matter of adjusting the namespace to be a group, instead of an individual account.

To create a new project within a group, complete the following steps:

1. From the top menu, click the icon + with the label New project.

2. Enter a Project path, using only lowercase letters and hyphens.

3. Next to the label Namespace, click the down arrow and select the appropriate group (Figure 12-10).

4. Complete each of the fields as you did previously to create a new project.

5. Click Create project.

The new project has been created and is available for development.

Figure 12-9. You can add multiple people to a group at the same time as long as they have the same role

Figure 12-10. The project Sea of Possibilities has been added to the group Neverending Story

If the project already existed, and you want to move it to a different namespace (individual account, or group), complete the following steps:

1. In the top menu, click gear icon for the Admin area.

2. From the left sidebar, click Projects.

3. Locate the project you want to reassign and click its name. You will be redirected to an admin summary for the project.

4. Locate the transfer form (Figure 12-11).

5. In the transfer form, click the down arrow on the drop-down box. A list of groups and users will appear. Select the group you want to transfer this project to.

6. Click Transfer.

Figure 12-11. The project transfer form allowing you to move a project to a different namespace

The project has been transfered to the new group. Previous group members will no longer have access to the project. Anyone with a local clone of the project will need to update the URL to use the new namespace for the project. (See Chapter 5 for details on working with remotes.)

Project Visibility

Within a given project, you can control the level of access per-project and per-role:

Private

Project access must be granted explicitly for each user.

Internal

The project can be cloned by any logged-in user.

Public

The project can be cloned without any authentication.

To adjust the project visibility settings, complete the following steps:

1. From the top menu, click the gear icon for Admin area.

2. From the left sidebar, click Projects.

3. Locate the project you wish to adjust and click its title.

4. From the project admin summary page, locate and click the button edit.

5. Locate the section of the form Visibility Level (Figure 12-12) and adjust the settings as appropriate for the access level you wish people to have (Private, Internal, or Public).

6. Locate and click Save changes.

Figure 12-12. Update the project visibility to one of Public, Internal, or Private

The visibility settings for your project have been adjusted.

Limiting Activities with Project Roles

Once users are able to see a project, you can further control the activities they can perform within the repository by assigning each person a specific role. A comprehensive checklist of all permissions is available from within your GitLab installation from help/permissions/permissions.

A quick summary of the functionality available to each role is as follows:

Guest

Able to create new issues and leave comments, and that’s it! This role may be appropriate for stakeholders who do not need access to the code, but should be involved in the development of the project.

Reporter

In addition to the Guest permissions, a Reporter is able to clone the project and create code snippets. You may want to grant CTOs this role because they should not be working on code anymore. (I’m mostly joking. I do think it’s great when managers are able to jump in and help out; I also think that managers should be focusing on the outward-facing tasks only they can accomplish.)

Developer

In addition to all of the previous permissions, Developers can also create new branches, create merge requests, push to nonprotected branches, add tags, write wiki pages, manage the issue tracker, and more! Most people on the team will likely be assigned this role. You can still limit their access to specific branches, so it’s okay to be generous with permissions at this point.

Master

In addition to the previous permissions, Masters are also able to create milestones, add new team members, push to protected branches, add deploy keys to the product, and edit the project itself. This role is appropriate for team leaders, and possibly savvy project managers who might need to change the team composition/access from time to time.

Owner

The final role is also able to change the project visibility, transfer the project to another namespace, and remove the project altogether. It is appropriate for nonteam administrators to have this role.

To update a person’s role within a group, complete the following steps:

1. From the top menu, click the gear icon for Admin area.

2. From the left sidebar, click Projects.

3. Locate the name of the project you want to update. Next to the name of the project there is a button labeled edit. Click this button. You will be redirected from the admin area to the project.

4. From the left sidebar, click Members.

5. Locate and click Edit group members. The list of members will be converted into a configuration list.

6. Locate the person whose role you want to change, and click the pencil icon. A new drop-down box will appear (Figure 12-13).

7. Update the drop-down box so that it contains the appropriate role for this person.

8. Click Save.

Figure 12-13. Update the role for a given team member

The new role has been applied.

Limiting Access with Protected Branches

The final level of access that GitLab offers is a per-branch setting. By default, the branch master is protected, and people with the role Developer cannot push to this branch. Instead, they are required to use the Merge Request process to have their work incorporated into the branch master for the repository. If you prefer having a shared access model, you can remove this protection.

To update which branches are protected within a given project, the branch must already exist. Once it exists within the repository, you can open or close the access. (Remember that when you first created the project you selected the default access setting for new branches.)

To set up access control for a given branch, complete the following steps:

1. From the top menu, click the gear icon for Admin area.

2. From the left sidebar, click Projects.

3. Locate the project you wish to adjust, and click the button labeled edit next to its name. This will take you to the project page, instead of the admin page.

4. From the left sidebar, click Settings, then Protected branches.

5. From the drop-down menu, select the branch you would like to protect (Figure 12-14).

6. Locate and click the button Protect.

Figure 12-14. Lock a branch so that it can only receive updates from accounts with the Role “Master” or “Owner” for this project or team

The branch can no longer be updated by the role Developer.

To remove this restriction, complete the following steps from the same screen:

1. Locate the section titled Already Protected (Figure 12-15).

2. Locate the branch you would like to update.

3. Click the button Unprotect.

Figure 12-15. Branches that have already been protected can be unprotected

Now people with the role Developer will be able to push commits to the branch you just updated.