Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Your Account and Finding Your Way Around

Create a GitLab account, set up your profile, learn the page layout, project URL patterns, GitLab references, quick search and notification settings.

A new GitLab user usually feels lost for about ten minutes, then finds the pattern. This lesson gives you that pattern up front: how to set up an account, how pages are organized, how addresses are built, and how to talk about issues and merge requests with short references.

Remember that menus move around between GitLab releases, so we describe areas by name ("the left sidebar", "the project's Settings") rather than by pixel position. If a label differs on your screen, look for the closest match.

Creating and securing your account

On GitLab.com you register with an email address or through a sign-in provider you already use. After that:

  1. Confirm your email. Some features stay locked until the address is verified.
  2. Set a username. It becomes your personal namespace, for example gitlab.com/ada, and appears in mentions such as @ada. Pick something you are happy to keep, because renaming changes all your URLs.
  3. Enable two-factor authentication. Open your avatar menu, choose Edit profile, then the Account page. An authenticator app is a good choice. A stolen password alone then cannot open your account.
  4. Add a profile picture and set your time zone. Due dates and activity times are shown in your zone.
  5. Add an SSH key or token so Git on your computer can talk to GitLab. The SSH keys and access tokens lesson covers this.

Self-managed instances often use single sign-on (LDAP or SAML) instead of local registration, and an administrator may need to approve new accounts.

The shape of the interface

Almost every page has the same structure.

  • Top bar: a search box (labelled Search or go to...), plus shortcuts to your to-do list, issues and merge requests assigned to you.
  • Left sidebar: context-sensitive navigation. At the top level it lists your projects, groups and activity. Inside a project it lists areas such as Plan, Code, Build, Deploy, Secure, Operate and Settings. Inside a group it shows group-wide versions of the same areas.
  • Main area: the page itself, for example a file list or a merge request.
  • Right panel: on issues and merge requests, the sidebar with assignees, labels, milestone and due date.

The key idea is context. The same menu item means something different depending on where you are. Issues inside a project lists that project's issues. Issues inside a group lists the issues of every project in that group.

Project URL patterns

GitLab puts its own pages under /-/ so they can never collide with a file or subgroup that happens to share a name. The pattern is host/namespace/project/-/page. The stand-in below builds the addresses of the main pages for any project.

Python Stand-in: build GitLab page addresses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A few more habits worth learning:

  • Add .diff or .patch to a commit or merge request address to get a raw patch.
  • A trailing /raw/ in a file address returns the plain file, useful in scripts.
  • The group version has the same shape: gitlab.com/groups/acme/-/issues.

References: the shorthand of GitLab

Anywhere you type Markdown (descriptions, comments, commit messages), GitLab turns short references into links and shows hover cards with the status. These are the ones you will use daily.

Reference Points to Example
#123 An issue Closes #123
!45 A merge request Reverts !45
%"v1.0" A milestone /milestone %"v1.0"
~bug A label /label ~bug
@ada A user (and sends a notification) Thanks @ada
&7 An epic Part of &7
$12 A snippet See $12
1a2b3c4 A commit (7 or more hex characters) Broken since 1a2b3c4

A reference to something in another project includes the path: acme/api#9 or acme/api!3. The stand-in below extracts references from a comment, the same kind of scanning GitLab performs when it builds links.

Python Stand-in: find GitLab references in a comment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The regular expression is a simplification (GitLab's real parser also checks that the thing exists and that you may see it), but it shows why a stray # in prose sometimes becomes a link.

Searching and moving quickly

  • Press / anywhere to focus the search box. Search inside a project to find code, issues, merge requests, commits and wikis for that project only; search from a group or the top level for wider results. Advanced code search across an instance may need extra infrastructure on self-managed servers.
  • Press ? to open the list of keyboard shortcuts. Shortcuts differ between versions, so treat that list as the source of truth.
  • The to-do list collects every place someone mentioned you, assigned you, or requested your review. Clear it like an inbox.
  • Use bookmarks of filters: after you filter issues by label and assignee, the URL contains the filter, so you can save or share it.

Notifications

By default you receive email for things you are involved in: issues you created or were assigned, threads you commented on, and mentions. Adjust this in two places.

  1. Global setting in your profile (the Notifications page): a default level such as Participate or On mention.
  2. Per group or project: the bell button on a group or project page lets you choose Global, Watch, Participate, On mention, Disabled or Custom.

For a single issue or merge request, the right panel has a notifications toggle. Unsubscribing there silences just that thread. If your inbox is flooded, lowering project-level watching is almost always the right fix.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does GitLab put its own pages under /-/ in a URL?

    The /-/ separator marks everything after it as a GitLab feature page, so a subgroup called issues cannot be confused with the Issues page.
  2. 2. What does the reference ~bug usually point to?

    The tilde references labels. Users use @, milestones use %, snippets use $.
  3. 3. You are inside a group and open Issues from the sidebar. What do you see?

    Sidebar items are context-sensitive: at group level they aggregate across the group's projects.
  4. 4. Which notification level is a sensible fix when a busy project floods your email?

    Project-level notification settings override your global default, so you can quiet a single noisy project.

Summary

  • Secure your account with two-factor authentication and add your SSH key or token early.
  • The interface is context-sensitive: the same menu item behaves differently in a group and in a project.
  • Feature pages live under /-/, giving predictable addresses such as /-/issues/42.
  • References like #, !, %, ~, @, & and $ turn plain text into links.
  • Tune notifications globally and per project to keep your inbox manageable.

Next: Groups, Projects and Namespaces