< GitLab

Where should your project live?

You have two options:

  1. Host the project under your personal namespace. This is appropriate and expected for things which are of benefit in the Wikimedia movement and/or the MediaWiki ecosystem which are:
    • Personal or user-specific tooling such as dotfiles
    • Early experimental prototypes and short-lived exploratory work
    • Forks of projects you can't push to directly, but wish to make merge requests for
  2. Host the project under a group. This is appropriate for:
    • Long-lived, shared projects
    • ...that benefit the Wikimedia movement and/or the MediaWiki ecosystem

Supported GitLab projects live in a group named for the functional area of code, under the top-level /repos. This gives access to a shared pool of CI runners.

There are some exceptions to this layout, where there are differences in policy around project trust and access to CI runners:

Users should typically be added to the project's group with an appropriate access level, rather than to the specific project.

Locating a group

First, check the list of subgroups under repos to see if an appropriate group already exists. Most of the existing ones correlate to WMF teams or affiliate organizations, or large functional areas like MediaWiki.

If you see a group that seems like a match, view the group and click on "Subgroup information" in the upper lefthand corner. Then navigate to "Members" to see existing members of the group. Ask one of them to invite you to the group. (TODO: What's the best general contact mechanism here? Phabricator form?)

For projects traditionally under the mediawiki namespace on Gerrit, we're porting most of the existing structure across:

  • Extensions: repos/mediawiki/extensions/[project name]
  • Skins: repos/mediawiki/skins/[project name]
  • Services: repos/mediawiki/services/[project name]

If your new project fits in one of these categories, create or request a project under the appropriate group.

info template: Note that Gerrit supports parent repositories which contain both code and child repos. For example, on Gerrit mediawiki/extensions is both a git repo with code and a container for extension repos. This is not possible on GitLab, so mediawiki/extensions is a group and the code repo there is moving to mediawiki/extensions/all.

Creating a new group

If you do not find an appropriate group but think one should be created please use this form to request a new group.

Keep in mind that groups may only contain other groups and individual projects. They may not themselves be a code repository, so you may have to change project layouts you are familiar with from Gerrit.

Creating a new project

  • Visit https://gitlab.wikimedia.org and make sure you're signed in with your Wikimedia developer account.
  • Click "Menu"
  • Under "Projects", click "Create new project"
  • Click "Create blank project" or "Create from template"
    • "Create from template" will prompt you to select from a list of templates, then on to the project creation form
    • Keep in mind that templates may include use of features which are not supported on the Wikimedia instance, such as issues and wikis. If so, these will be automatically disabled at some point after your project is created.
  • Look under "Project URL" and click the "Pick a group or namespace" field
  • For a project under your user namespace, type your username in the search box or scroll down until you see the "Users" section and select your username
  • For a project under a group, type the group name in the search box or scroll until you see it
  • Click "Create project"

Migrating a project

Importing code to GitLab

  • Click on New Project > Import Project
  • Choose Repository by URL
  • Get URL from source repository
    • Go to source code management tool (Gerrit, GitHub, gitlab.com, etc.), find https URL
    • Paste URL into "Git repository URL"
    • Name can be free-form
    • Slug should correspond to previously existing repo name
    • Fill out project description in detail
    • Visibility will be public by default, you will likely not be able to change this.
    • Press "Create Project"

This will create a complete copy of the repository, including all branches and review notes from Gerrit.

Branch renaming

By policy (see phab:T281593), repositories on GitLab should use "main" as a default branch name, unless they already use some other default than "master", such as "production" or "wmf/stable":

  • New branch -> Called main
  • Settings -> Repository -> Branch defaults -> main
  • Settings -> Repository -> Protected branches -> add main -> Protect
  • Branches -> trash can icon for master, type master

Updating references

All references to the repo need to be updated. This may include existing checkouts, submodule URLs, scripts, Puppet configuration, etc.

Tip: Use codesearch to find references in Wikimedia code.

Updating existing checkouts

git remote set-url origin [gitlab url]
git fetch
git checkout main
git branch -d master

Updating .gitreview

If there's an existing .gitreview, update the file w/ gitlab info (for users who may want to use gerritlab), using the example below as a template. Replace NNNN with your project id (which appears in the top left of the page when you visit the repo in https://gerrit.wikimedia.org).

[origin]
host=https://gitlab.wikimedia.org
project_id=NNNN
target_branch=main
remove_source_branch=True

Archiving old projects

  • TODO: Remove from CI

Mirroring projects to other code forges

See GitLab/Mirroring projects.

Enabling GitLab CI for a project

For new projects, see GitLab/Workflows/CI.

For projects with an existing .pipeline/config, see GitLab/pipeline conversion.

To publish docs to doc.wikimedia.org, see GitLab/Publishing docs

TODOs

This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.