GitLab 101

What is GitLab
GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager providing wiki, issue-tracking and CI/CD pipeline features, using an open-source license.

See the Demo Video

Summarized: GitLab is a complete DevOps platform, delivered as a single application.

Terminology
1.Board

1. Definition: make it possible to visualize and manage lists of issues which can be defined by one of three ways: Labels, Team members, and Milestones.

2.Branch

1. Definition: a version of a project’s working tree. You create a branch for each set of related changes you make. This keeps each set of changes separate from each other, allowing changes to be made in parallel, without affecting each other.

3.Commit

1. Definition: a change, or set of changes, to one or more files in the source code on a given Git branch. A commit allows you to mark the project in its current state as a kind of snapshot in time.

2. Example: This is a commit.

4.DevOps

1. Definition: is a set of practices that combines software development and information-technology operations which aims to shorten the systems development life cycle and provide continuous delivery with high software quality.

5.Epic

1. Definition: provides a way to organize and manage a set of issues and sub-epics that share the same theme.

2. Example: This is an epic.

6.Git

1. Definition: is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.

7.Groups
Definition: are used to manage one or more related projects at the same time. You can use groups to manage permissions for your projects. If someone has access to the group (it’s a member of the group), they get access to all the projects, issues, and merge requests in the group.

1. Example: This is a group.

8.Handbook-first approach

1. Definition: it’s a process that describes documenting in the handbook before taking an action, without using other forms of communication. This ensures no duplication and having the Handbook up to date.

9.Issue

1. Definition: the fundamental medium for collaborating on ideas and planning work in GitLab

2. Example: This is an Issue.

10.Labels

1. Definition: They help you organize and tag your work so you can track and find the work items you’re interested in. You can use descriptive titles like bug, feature request, or docs, as well as customizable colors.

2. More information on: labels.

11.Local

1. Definition: your machine. You can also use GitLab locally, on your machine, not just in the browser.

2. Example: If someone says to do something locally that means to open the terminal on your computer to make a change.

12.Markdown

1. Definition: a lightweight markup language with plain-text-formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML.

2. Example: Take a look at our GitLab Markdown Guide

13.Milestones

1. Definition: are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. They allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date.

2. More information on: milestones

14.Merge Request

1. Definition: allows you to visualize and collaborate on the proposed changes to source code that exist as commits on a given Git branch. A Merge Request (MR) is the basis of GitLab as a code collaboration and version control platform. It is as simple as the name implies: a request to merge one branch into another.

2. Example: This is a Merge Request.

15.Open Source

1. Definition: denotes software for which the original source code is made freely available and may be redistributed and modified.

2. Example: Our GitLab handbook is open source because anyone can make changes and contribute to it.

16.Project

1. Definition: used for hosting your codebase, as an issue tracker, collaborate on code, and continuously build, test, and deploy your app with built-in GitLab CI/CD.

2. Example: This is a project.

17.Source Code

1. Definition: a text listing of commands to be compiled or assembled into an executable computer program.

18.SSH Key (SSH = Secure Shell)

1. Definition: a cryptographic network protocol for operating network services securely over an unsecured network.

19.Terminal

1. Definition: is a command line input console used for entering data into, and displaying or printing data from a computer or a computing system.

20.To-Do lists

1. Definition: are lists of issues, merge requests or epics where you were mentioned in.

21.Weight

1. Definition: allow you to get a better idea of how much time, value or complexity a given issue has or will cost.

2. More information on: issue weights

How to open a GitLab Issue
To open a GitLab issue:

Navigate to the project where you want to open the issue

1. How do you know what project to use? - Find the project that is most relevant to the issue you want to create. For example if you wanted to open an issue on something relating to our benefits, you would open an issue in the Total Rewards project. If you do open an issue in an incorrect project, you can move it. We will cover that as the next topic.

2.
Select "Issues" in the left hand side

3.
Click the green "New issue" button in the top right

4.
Add in a Title for the issue

5.
In the Description add any relevant information

6.
Click the "preview" button at the top of the issue box to preview your issue and make sure you have formatted everything correctly

7.
Decide whether the issue needs to be confidential or not

8.
How do you know if your issue should be confidential or not?

9.
Transparency is one of our values so we try to be open about as many things as possible. Only use confidential issues, if the issue must contain non-public information.

10.
Assign the issue to the relevant person (that might be you!)

11.
If relevant: assign a milestone

12.
If relevant: add a label (or multiple)

13.
If relevant: add a weight

14.
If relevant: add a due date
Click the green "Submit issue" at the bottom
See the Video

How to move a GitLab Issue
It's possible that an issue will be opened in an incorrect project. If that happens, it is easy to move it to the correct project.

To move a GitLab issue:

Navigate to the issue you want to move
In the right hand menu bar, scroll all the way to the bottom
Select "Move issue"
Search for the project you want to move it to and click on it
Click the blue "Move" button
It will move the issue, and the link will change according to the new location of the issue
See the video

How to comment on a GitLab Issue
To comment on a GitLab issue:

1. Open the issue that you want to comment on

2. If there are other comments, scroll to the bottom and add your comment there

3. It is also possible that you may want to reply to someone's comment that is already on the issue. To do this, you will click the speech balloon on their comment (when you hover over it it will say "reply to comment") and it will add a box for you to type your reply.

4. When you are done typing your comment, click the green "Comment" button to add it to the issue

How to search for a GitLab Issue
Knowing how to search for a GitLab issue can be very helpful, especially if you had been looking at it but hadn't made a comment or been tagged in it. If you know some key words that were in the issue, you should be able to find it! Here's how:

1. Go to gitlab.com

2. In the top right click on the search bar

3. Type in text you want to search for and hit enter

4. On the next screen, select the group the issue is in that you are searching for. In this instance the group is people-group

5. Then, select the project the issue is in that you are searching for. In this instance the project is gitlab-tool-training

6. Click on the "issues" tab under the search bar to see all issues with the text you are searching for in that specific group and project.

7. This docs resource has helpful tips on searching for an Issue.

Video: How to search for a GitLab Issue (~4 minutes)

GitLab Issue Labels and Issue Boards
Tags or labels are used to help sort and search for GitLab Issues.

Each GitLab Project has an Issue Board. These can be set up similar to how a kanban board would look. You can add different lists to the Issue Board based on "labels" in the project.

Video: GitLab Issue Labels and Issue Boards (~4 minutes)

What is a GitLab Merge Request
As you learned in the technical terminology portion, a GitLab Merge Request (MR) is a request to merge one branch into another. We want to reiterate that this is a "request" meaning you aren't going to break GitLab with just submitting your MR.

How to create a GitLab Merge Request (i.e. How to make an update to the handbook)
To create a merge request:

1. Find the page of the handbook that you want to make the change to. (ex. Learning & Development)

2. Once you are on the page you want to make a change to, scroll all the way to the bottom and select "View page source"

3. This will redirect you to the file on the www-gitlab-com project

4. Then you will need to click the blue "Edit" button

5. Select the soft wrap/no wrap button in the top right (just above the text box) to how you prefer

6. Find the portion of the page you were wanting to change and make your proposed changes.

7. Update the "Commit message" - this should describe the changes you made in a few words (ex. Add Values Certification to Page)

8. Update the "Target Branch" - this will be similar to the commit message, but shorter and using dashes instead of spaces. Every branch name must be unique.

9. Click "Commit changes" - don't worry, this will just create your merge request, it will not make your changes reflect right away (someone still has to merge it before your changes will be reflected).

10. On the next page the "Title" will auto populate as the Commit message from the previous page

11. Answer the questions in the "Description section"

12. Assign the merge request to your manager for review

13. Click "submit merge request"
    Video: How to create a GitLab Merge Request (~10 minutes)
    How to search for a GitLab Merge Request
    You can search for a GitLab Merge Request in the same way as you search for a GitLab Issue outlined above. The only difference is to select the "Merge requests" button in the top right, rather than the Issues button.

Helpful Tips for Merge Requests

1. Who can merge your Merge Request (MR)? - your manager should have the ability to merge (i.e. maintainer access). If they don't have the ability to merge, they will know who you can assign it to for review/merging.

2. If you assign your MR to someone who isn't a Maintainer, there will be a yellow triangle with an exclamation point by their picture.

3. Soft Wrap - when you are editing your MR, you can either select soft wrap or no wrap. If you select "soft wrap" you will be able to see all of the text in one screen. If you select "no wrap" (which is the default) you will have to scroll to the right if the text on the line is wider than the page.

4. Squash Commits - when obtaining a merge request, there is an option to enable or disable “Squash commits when merge request is accepted”. If enabled, it combines all your merge request’s commits into one and retain a clean history.

5. Delete Branch - when creating or editing your merge request, you can also select the “Delete source branch when merge request accepted” option.