Merge pull request #1504 from HonkingGoose/update-gitlab-section

Author: ben

book/04-git-server/sections/gitlab.asc

@@ -2,60 +2,58 @@
 
 (((serving repositories, GitLab)))(((GitLab)))
 GitWeb is pretty simplistic though.
-If you're looking for a more modern, fully featured Git server, there are some several open source solutions out there that you can install instead.
-As GitLab is one of the more popular ones, we'll cover installing and using it as an example.
-This is a bit more complex than the GitWeb option and likely requires more maintenance, but it is a much more fully featured option.
+If you're looking for a modern, fully featured Git server, there are several open source solutions out there that you can install instead.
+As GitLab is one of the popular ones, we'll cover installing and using it as an example.
+This is harder than the GitWeb option and will require more maintenance, but it is a fully featured option.
 
 ==== Installation
 
-GitLab is a database-backed web application, so its installation is a bit more involved than some other Git servers.
-Fortunately, this process is very well-documented and supported.
+GitLab is a database-backed web application, so its installation is more involved than some other Git servers.
+Fortunately, this process is well-documented and supported.
+GitLab strongly recommends installing GitLab on your server via the official Omnibus GitLab package.
 
-There are a few methods you can pursue to install GitLab.
-To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab[], and tweak the configuration to match your particular environment.(((bitnami)))
-One nice touch Bitnami has included is the login screen (accessed by typing alt+→); it tells you the IP address and default username and password for the installed GitLab.
+The other installation options are:
 
-[[bitnami]]
-.The Bitnami GitLab virtual machine login screen
-image::images/bitnami.png[The Bitnami GitLab virtual machine login screen]
+* GitLab Helm chart, for use with Kubernetes.
+* Dockerized GitLab packages for use with Docker.
+* From the source files.
+* Cloud provider such as AWS, Google Cloud Platform, Azure, OpenShift and Digital Ocean.
 
-For anything else, follow the guidance in the GitLab Community Edition readme, which can be found at https://gitlab.com/gitlab-org/gitlab-ce/tree/master[].
-There you'll find assistance for installing GitLab using Chef recipes, a virtual machine on Digital Ocean, and RPM and DEB packages (which, as of this writing, are in beta).
-There's also ``unofficial'' guidance on getting GitLab running with non-standard operating systems and databases, a fully-manual installation script, and many other topics.
+For more information read the https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/README.md[GitLab Community Edition (CE) readme].
 
 ==== Administration
 
 GitLab's administration interface is accessed over the web.
-Simply point your browser to the hostname or IP address where GitLab is installed, and log in as an admin user.
-The default username is `[email protected]`, and the default password is `5iveL!fe` (which you will be prompted to change as soon as you enter it).
-Once logged in, click the ``Admin area'' icon in the menu at the top right.
+Simply point your browser to the hostname or IP address where GitLab is installed, and log in as the admin user.
+The default username is `[email protected]`, and the default password is `5iveL!fe` (which you must change right away).
+After you've logged in, click the ``Admin area'' icon in the menu at the top right.
 
 [[gitlab_menu]]
 .The ``Admin area'' item in the GitLab menu
 image::images/gitlab-menu.png[The ``Admin area'' item in the GitLab menu]
 
 ===== Users
 
-Users in GitLab are accounts that correspond to people.
-User accounts don't have a lot of complexity; mainly it's a collection of personal information attached to login data.
-Each user account comes with a *namespace*, which is a logical grouping of projects that belong to that user.
+Everybody using your GitLab server must have an user account.
+User accounts are quite simple, they mainly contain personal information attached to login data.
+Each user account has a *namespace*, which is a logical grouping of projects that belong to that user.
 If the user +jane+ had a project named +project+, that project's url would be `http://server/jane/project`.
 
 [[gitlab_users]]
 .The GitLab user administration screen
 image::images/gitlab-users.png[The GitLab user administration screen]
 
-Removing a user can be done in two ways.
+You can remove a user account in two ways:
 ``Blocking'' a user prevents them from logging into the GitLab instance, but all of the data under that user's namespace will be preserved, and commits signed with that user's email address will still link back to their profile.
 
 ``Destroying'' a user, on the other hand, completely removes them from the database and filesystem.
 All projects and data in their namespace is removed, and any groups they own will also be removed.
-This is obviously a much more permanent and destructive action, and its uses are rare.
+This is obviously a much more permanent and destructive action, and you will rarely need it.
 
 [[_gitlab_groups_section]]
 ===== Groups
 
-A GitLab group is an assemblage of projects, along with data about how users can access those projects.
+A GitLab group is a collection of projects, along with data about how users can access those projects.
 Each group has a project namespace (the same way that users do), so if the group +training+ has a project +materials+, its url would be `http://server/training/materials`.
 
 [[gitlab_groups]]
@@ -70,9 +68,9 @@ The types of permissions are too numerous to list here, but GitLab has a helpful
 
 A GitLab project roughly corresponds to a single Git repository.
 Every project belongs to a single namespace, either a user or a group.
-If the project belongs to a user, the owner of the project has direct control over who has access to the project; if the project belongs to a group, the group's user-level permissions will also take effect.
+If the project belongs to a user, the owner of the project has direct control over who has access to the project; if the project belongs to a group, the group's user-level permissions will take effect.
 
-Every project also has a visibility level, which controls who has read access to that project's pages and repository.
+Every project has a visibility level, which controls who has read access to that project's pages and repository.
 If a project is _Private_, the project's owner must explicitly grant access to specific users.
 An _Internal_ project is visible to any logged-in user, and a _Public_ project is visible to anyone.
 Note that this controls both `git fetch` access as well as access to the web UI for that project.
@@ -86,9 +84,9 @@ This is a great way to connect your Git repositories and GitLab instance to the
 ==== Basic Usage
 
 The first thing you'll want to do with GitLab is create a new project.
-This is accomplished by clicking the ``+'' icon on the toolbar.
+You can do this by clicking on the ``+'' icon on the toolbar.
 You'll be asked for the project's name, which namespace it should belong to, and what its visibility level should be.
-Most of what you specify here isn't permanent, and can be re-adjusted later through the settings interface.
+Most of what you specify here isn't permanent, and can be changed later through the settings interface.
 Click ``Create Project'', and you're done.
 
 Once the project exists, you'll probably want to connect it with a local Git repository.
@@ -113,19 +111,19 @@ Each project's home page shows recent activity, and links along the top will lea
 
 ==== Working Together
 
-The simplest way of working together on a GitLab project is by giving another user direct push access to the Git repository.
+The simplest way of working together on a GitLab project is by giving each user direct push access to the Git repository.
 You can add a user to a project by going to the ``Members'' section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>).
-By giving a user an access level of ``Developer'' or above, that user can push commits and branches directly to the repository with impunity.
+By giving a user an access level of ``Developer'' or above, that user can push commits and branches directly to the repository.
 
 Another, more decoupled way of collaboration is by using merge requests.
 This feature enables any user that can see a project to contribute to it in a controlled way.
 Users with direct access can simply create a branch, push commits to it, and open a merge request from their branch back into `master` or any other branch.
-Users who don't have push permissions for a repository can ``fork'' it (create their own copy), push commits to _that_ copy, and open a merge request from their fork back to the main project.
+Users who don't have push permissions for a repository can ``fork'' it to create their own copy, push commits to _their_ copy, and open a merge request from their fork back to the main project.
 This model allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users.
 
 Merge requests and issues are the main units of long-lived discussion in GitLab.
 Each merge request allows a line-by-line discussion of the proposed change (which supports a lightweight kind of code review), as well as a general overall discussion thread.
 Both can be assigned to users, or organized into milestones.
 
 This section is focused mainly on the Git-related features of GitLab, but as a mature project, it provides many other features to help your team work together, such as project wikis and system maintenance tools.
-One benefit to GitLab is that, once the server is set up and running, you'll rarely need to tweak a configuration file or access the server via SSH; most administration and general usage can be accomplished through the in-browser interface.
+One benefit to GitLab is that, once the server is set up and running, you'll rarely need to tweak a configuration file or access the server via SSH; most administration and general usage can be done through the in-browser interface.