GitLab How-To
Everyone in our company uses GitLab. Why did we choose it? There are plenty of business tools out there: CRMs, HR platforms, task and time trackers, kanban boards, Gantt and burn down charts, etc. All of these tools are not standardized, poorly connected, and suffer from security vulnerabilities. On the tech team side, the software zoo is usually centered around a git repository, which is vertically integrated through the whole software development cycle. Over the past years, tools like GitLab and GitHub have built an ecosystem around them that can replace most of the business software you used in the past. While some concepts you’ll come across in GitLab may not sound familiar, you’ll quickly realize their potential as the building blocks of our business processes. In addition to this, learning these fundamental concepts will give you the ability to effectively communicate with the tech team without leaving GitLab, removing the need for endless calls and note taking.
Issues
Issues are the main building blocks of any work we do. An issue is an atomic unit of work usually performed by one person. Always create an issue and post comments in it when working on something, however small your task might be.
Additional GitLab documentation - Issues
Description
When creating an issue, try to provide an exhaustive description with clear and achievable and goals, especially if you plan to assign the issue to someone else. Some types of issues require you to follow issue templates you can find in the dropdown menu.
Take advantage of the markdown features, such as task lists. Breaking things down not only makes the work easier and less prone to misunderstandings, but also allows you to follow the progress as the assignee checks the boxes.
Assignees
If you create an issue, you need to assign it to someone unless you want to do it yourself (in which case you should assign it to yourself). You can assign the issue to multiple people, but always clearly state who is responsible for what.
Deadlines
Always put a due date to your issue so that everyone understands the progress you make over the issue. If you think you won’t be able to complete the issue on time, indicate this as soon as possible by commenting in the issue and moving the deadline. Don’t quietly let the deadline pass.
Labels
Labels are important for everyone to understand the scope and the status of the issue without going through the comments. Having relevant labels assigned to the issue is indispensable for filtering them and using boards.
Always have at least one of the status labels assigned to the issue and keep updating them as you progress through this issue. When done, assign status::done to the issue so the creator can check your work and close the issue if everything is okay.
Time Cap label We often need to limit the time we spend on a specific issue to make sure it doesn’t become a time sink. Unless additional details are provided, setting this label means:
- No team member can spend more than an hour per week working on this issue.
- No team member can send more than one external email per week concerning this issue.
- All time spent working on this issue needs to be recorded.
There are other labels and you can create on your own if needed.
Additional GitLab documentation - Labels
Boards
You can leverage labels to arrange and view existing issues in the boards section. You can create your own Kanban board or use one created by others to track the status of issues, both on project and group levels.
Additional GitLab documentation - Issue boards
Milestones
The purpose of milestones is to show progress on a focused group of issues. Milestones are not used to filter or to group issues - we have labels for that. Instead, think of milestones as wars and issues as battles. It’s often okay to sacrifice to lose individual issues in order to win the milestone.
As illustrated in the Inca Responsibility Pyramid, while success of an issue is the warrior’s responsibility, milestones are overseen by officers. They attach individual issues to the milestones and make sure that they get done before the deadline. In case of potential delays, it is their responsibility to suggest a workaround and coordinate a fix.
Milestones are SMART goals - Specific, Measurable, Attainable, Realistic, and Timely goals. Don’t create milestones for abstract efforts that are hard to declare finished.
Additional GitLab documentation - Milestones
Repository
Repository is where the code and documentation is kept. As you’ll notice, even our business projects use their git repository to keep files. It might seem easier to just use Google Docs, and sometimes it is, usually right until you go beyond 2 collaborators working on small documents. Git is what enables us to collaborate without stepping on each other’s toes and to resolve any contribution conflicts. Whenever you want to contribute to the repository, you can create a branch and a merge request from the drop-down menu below the issue description:
This action creates your own personal space (your branch) that is cloned from the main repository (master branch) as well as a page to track the differences between the two (merge request).
Additional GitLab documentation - Repository
Branches
You can work on individual files directly from the project’s repository page or take your work to the Web IDE, a more powerful way to work with multiple files at the same time. In any case, make sure to chose your personal working branch in the top left corner when you make changes.
Additional GitLab documentation - Branches
Merge Requests
Merge request is a powerful way to have other people review your work in progress. Just like with your issues, you need to assign someone to your merge request. Instead of commenting, though, you should make commits by saving changes to your branch. Whenever you’re ready to submit your work for review, mark your merge request as ready.
This will remove the “draft” tag and allow your review to merge your work with the main branch.
Commit often to show others your progress and make it easier for your review your contributions as they are ready instead of going through thousands of new lines at the end. The review may choose to add comments to specific lines of your contributions. Those will need to be addressed before merging your work to them master branch.
Try completing “GitLab Repository Basics” issues in your personal HR project to practice working with repositories.