GitLab/Workflows

= Introduction =

This is an effort to document workflows for using our GitLab instance for Wikimedia development. Depending on the result of the consultation, it may evolve into a reference for production use.

See Gerrit to GitLab for pointers on how specific features and tasks translate across systems.

= Registering an account on GitLab =

Accounts on the gitlab instance are tied to Wikimedia developer accounts. For help creating a developer account, visit Help:Create a Wikimedia developer account.

Once you have a developer account, visit gitlab.wikimedia.org and click "Sign In" in the upper-righthand corner of the window. You'll be redirected to idp.wikimedia.org to enter your credentials, and then back to the GitLab instance once you've signed in.

Add an SSH key
Visit the SSH settings in your profile and add a public key. See the GitLab documentation for more details on this process.

Add two-factor authentication
You may be required to use 2-factor authentication to access most projects on GitLab.

Click on your user icon, then "Edit profile" or "Preferences", followed by "Account", and the "Manage two-factor authentication" button. From here you can set up an authenticator app, or use a hardware device (such as a YubiKey) as your second factor.

See the upstream GitLab docs on two-factor authentication for more detail.

= Hosting a project on GitLab =

See Hosting a project on GitLab for help getting a project onto the GitLab instance.

= Making a GitLab Merge Request =

Create a branch
Use the convention :

Make your changes
Write some code and save your changes.

Stage and commit your changes
Let's say you've edited the  in. You should be able to see this using :

Stage the file and commit:

You should now be able to see this commit in the log:

Fork the repository


If you don't have developer-level permissions on the project you'd like to contribute to, you'll first need to copy the repository to your own account. This is known as "forking". Visit the repository page, for example https://gitlab.wikimedia.org/repos/releng/blubber, and click "Fork" in the upper righthand corner.

Next, add a remote for your fork:

If you've done this successfully, it should show up in your remotes:

Push your commit to GitLab
If you have commit access, you can push directly to a branch on the origin with.

If you're using a fork, push instead to the remote you added above with.

Create a Merge Request on GitLab
You may notice that GitLab responded to the push with a link to create a new merge request from your branch. You can follow that link directly, or visit the GitLab instance, navigate to the branch list for the repository, and click the "Merge request" button in the listing.



Provide an informative title and description for the merge request, and @-mention the users you'd like to see review your code. You should be able to use the full range of syntax in GitLab Markdown.

Merge options
In the "Merge options" section:


 * Check "Delete source branch when merge request is accepted" to avoid cluttering the repository with already-merged feature branches. (This is probably the default.)
 * In the general case, you should use "Squash commits when merge request is accepted". (This is probably the default.)
 * This can be omitted if you plan to submit a merge request containing multiple commits.
 * If the logical structure of your change dictates multiple commits, you may use interactive rebase to achieve the desired history and force push to your work branch before merge. This is an advanced workflow, but supported.
 * Check "Allow commits from members who can merge to the target branch", unless you have a specific reason to prevent others from making changes.

Draft / WIP merge requests
If you want to let reviewers know that your change is a work in progress and prevent accidental merges, you can use a draft merge request. Prefix your merge request title with. This will display a notice and disable "merge" button for reviewers.

Making new commits
Typically, you'll just make a new commit on your work branch, as usual, and push to the correct remote:

Or:

The new commit makes it very easy for reviewers to see what changed since they last saw the merge request, and will be squashed into the other commits when the pull request is merged, assuming that the pull request is set up to squash commits on merge (as recommended above).

Force pushing to a branch
If, instead, you wish to rewrite the history of the branch, for example by altering an existing commit or rebasing your work on top of upstream changes, GitLab allows force-pushing to a branch that's associated with a merge request.

This is mainly suitable for merge requests which are not meant to be squashed on merge, typically because they contain two or more commits that should remain separate. In that case, you clean up the history locally and then force-push it to update the merge request.

Getting code review
Once you've submitted a merge request, someone will need to review it. In addition to @-mentioning appropriate users in your merge request description or comments, you can assign a single reviewer. Do this by clicking "Edit" on "Assignees" in the sidebar at the right side of the page when viewing a merge request.

Please see Code review for documentation on reviewing code.

Update your remote
When we migrate from Gerrit to GitLab you will need to update your remote repository url locally:

Rename "master" to "main"
As part of the migration to GitLab, we are changing the mainline branch from  →.

To update your local checkout (after changing your remote):

This transition is documented on Phabricator on T281593 (and T254646).

Sources and further reading
There's a lot of quality documentation available for GitLab, although navigating it can be a bit tricky.


 * Contributors to the talk page for the GitLab consultation have reported on various workflow experiments.
 * GitLab User Docs
 * Getting started with merge requests
 * How to create a merge request
 * KDE's GitLab documentation - we're borrowing the convention of work branches from this, and it's a well-written document overall.
 * This document is inspired by and borrows structure from Gerrit/Tutorial.
 * GitLab/Gerrit to GitLab documents how features / concepts map between systems.