GitLab/Hosting a project on 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:
 * 2) * Personal or user-specific tooling such as dotfiles
 * 3) * Early experimental prototypes and short-lived exploratory work
 * 4) * Forks of projects you can't push to directly, but wish to make merge requests for
 * 5) Host the project under a group. This is appropriate for:
 * 6) * Long-lived, shared projects
 * 7) * ...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:
 * gitlab:toolforge-repos
 * gitlab:cloudvps-repos

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, 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
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

 * 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"

Mirroring a project to GitLab

 * Always use  for primary branch: See T281593
 * TODO: How to rename branches
 * 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 ).
 * TODO: Copying the repo over (including review metadata with ).

Preparations

 * Create a repo on Github, if you haven't already. This can be done by importing the Gitlab repo.
 * Create a personal access token in Github. This is done on https://github.com/settings/tokens?type=beta. Add permission "Contents" -> "Access: Read and write".

Set up mirroring

 * 1) In the repo view in Gitlab go to "Settings" (bottom in the left hand menu) -> "Repository".
 * 2) Expand "Mirroring repositories".
 * 3) Enter the HTTPS URL of the Github repo, same as the clone URL, but include username, i.e. https://username@github.com/....git.
 * 4) Leave "Mirror direction", it seems you can't change it anyway.
 * 5) Select "Password" for "Authentication method".
 * 6) In "Password" enter the personal access token from your Github account.
 * 7) Click "Mirror repository". You should get a message at the top of the page saying it worked.

Test mirroring

 * 1) Make a commit in the Gitlab repo.
 * 2) Click the circular arrows ("Update now") to start an update. If it goes through changes should be pushed to the Github repo.

TODOs

 * TODO: Remove from CI
 * TODO: Update Phabricator mirroring?
 * TODO: Updating external references and docs
 * TODO: Changing remotes on existing clones
 * TODO: cf https://phabricator.wikimedia.org/project/profile/2829/

Enabling GitLab CI for a project

 * TODO: This is likely a guide unto itself
 * TODO: Adding