GitLab/Hosting a project on GitLab


Where should your project live?[edit]

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[edit]

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, but in future they will include 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?)

Creating a new group[edit]

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

Creating a new project[edit]

  • Visit 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[edit]

Mirroring a project to GitLab[edit]

  • Always use main for primary branch: See phab:T281593
    • TODO: How to rename branches
      • it branch -m main
  • Don't use issues - these will be automatically disabled anyway
  • Don't use wikis - these will be automatically disabled anyway
  • TODO: Project settings
  • TODO: Copying the repo over (including review metadata with --mirror).

Archiving the old project on Gerrit, GitLab, or Phabricator[edit]

  • TODO: Remove from CI
  • TODO: Update Phabricator mirroring?
  • TODO: Updating external references and docs
  • TODO: Mirroring to GitHub
  • TODO: Changing remotes on existing clones

Enabling GitLab CI for a project[edit]

  • TODO: This is likely a guide unto itself
  • TODO: Adding .gitlab-ci.yml