Contribute to GitLab development
Thank you for your interest in contributing to GitLab. This guide details how to contribute to the development of GitLab.
For a first-time step-by-step guide, see Tutorial: Make a GitLab contribution.
How to contribute
- Read the code of conduct.
- Choose or create an issue to work on.
- Set up the GitLab Development Kit.
- Open your merge request.
Your merge request is triaged, reviewed, and can then be incorporated into the product.
Code of conduct
We want to create a welcoming environment for everyone who is interested in contributing. For more information about our commitment to an open and welcoming environment, see our Code of Conduct page.
Issues and merge requests should be in English and contain appropriate language for audiences of all ages.
Choose or create an issue
If you know what you’re going to work on, see if an issue exists. If it doesn’t, open a new issue. Select the appropriate template, and add all the necessary information about the work you are planning on doing. That way you can get more guidance and support from GitLab team members.
If you’re not sure what to work on, you can view issues with the
~Seeking community contributions
and ~quick win
label.
When you find an issue, leave a comment on the issue you want to work on. This helps the GitLab team and members of the wider GitLab community know that you will be working on that issue.
For details, see the issues workflow.
Set up the GitLab Development Kit
To write and test your code, you will use the GitLab Development Kit.
- Request access to the GitLab Community fork. Alternatively, you can create your own public fork, but will miss out on the benefits of the community forks.
- Some GitLab projects have a detailed contributing guide located in the README or CONTRIBUTING files in the repository. Reviewing these files before setting up your development environment will help ensure you get off to a good start.
- Do one of the following:
-
To run the development environment locally, download and set up the GitLab Development Kit. See the GDK README for setup instructions and Troubleshooting if you get stuck.
-
GDK is heavy. If you need to build something fast, by trial and error, consider doing so with an empty rails app and port it to GDK after.
-
To run a pre-configured GDK instance in the cloud, use GDK with Gitpod. From a project repository:
- On the left sidebar, select Search or go to and find your project.
- In the upper right, select Edit > Gitpod.
-
- If you want to contribute to the website or the handbook, go to the footer of any page and select Edit in Web IDE to open the Web IDE.
Open a merge request
Now Open a merge request to merge your code and its documentation. The earlier you open a merge request, the sooner you can get feedback. You can mark it as a draft to signal that you’re not done yet.
- In the merge request, fill out all the information requested in the template, like why you are introducing these changes and a link to the issue this merge request is attempting to close/fix.
- Add tests if needed, as well as a changelog entry.
- If the change impacts users or admins, update the documentation.
For details, see the merge request workflow.
How community merge requests are triaged
- When you create a merge request, the
@gitlab-bot
automatically applies the “~Community contribution” label. - In the 24-48 hours after you create the merge request, a Merge Request Coach will review your merge request and apply stage, group, and type labels.
- If a merge request was not automatically assigned, ask for a review by typing
@gitlab-bot ready
in a comment. If your code has not been assigned a reviewer within two working days of its initial submission, you can ask for help with@gitlab-bot help
. - The Merge Request Coach will assign the relevant reviewers or tackle the review themselves if possible.
The goal is to have a merge request reviewed within a week after a reviewer is assigned. At times this may take longer due to high workload, holidays, or other reasons. If you need to, look at the team page for the merge request coach who specializes in the type of code you have written and mention them in the merge request. For example, if you have written some front-end code, you should mention the frontend merge request coach. If your code has multiple disciplines, you can mention multiple merge request coaches.
For details about timelines and how you can request help or escalate a merge request, see the Wider Community Merge Request guide.
After your merge request is reviewed and merged, your changes will be deployed to GitLab.com and included in the next release!
Review process
When you submit code to GitLab, we really want it to get merged! However, we always review submissions carefully, and this takes time. Code submissions will usually be reviewed by two domain experts before being merged:
- A reviewer.
- A maintainer.
After review, the reviewer could ask the author to update the merge request. In that case, the reviewer would set the ~"workflow::in dev"
label.
Once the merge request has been updated and set as ready for review again (for example, with @gitlab-bot ready
), they will review the code again.
This process may repeat any number of times before merge, to help make the contribution the best it can be.
Lastly, keep the following in mind when submitting merge requests:
- When reviewers are reading through a merge request they may request guidance from other reviewers.
- If the code quality is found to not meet GitLab standards, the merge request reviewer will
provide guidance and refer the author to our:
- Documentation style guide.
- Code style guides.
- Sometimes style guides will be followed but the code will lack structural integrity, or the reviewer will have reservations about the code’s overall quality. When there is a reservation, the reviewer will inform the author and provide some guidance.
- Though GitLab generally allows anyone to indicate approval of merge requests, the maintainer may require approvals from certain reviewers before merging a merge request.
- Sometimes a maintainer may choose to close a merge request. They will fully disclose why it will not be merged, as well as some guidance. The maintainers will be open to discussion about how to change the code so it can be approved and merged in the future.
Tips
- Small MRs are the main key to a great review.
- Make sure to read our merge request guidelines for contributors before you start for the first time.
- Automated testing is required. Take your time to understand the different testing levels and apply them accordingly.
- Make sure to have a great description that includes steps to reproduce your implementation.
- Make sure to follow our commit message guidelines.
Closing policy for issues and merge requests
- For the criteria for closing issues, see the Issue Triage handbook page.
- For the criteria for closing merge requests, see the Merge Request Workflow.
Contributing to Premium/Ultimate features with an Enterprise Edition license
If you would like to work on GitLab features that are within a paid tier, also known as the code that lives in the EE folder, it requires a GitLab Enterprise Edition license. Request an Enterprise Edition Developers License according to the documented process.
Get help
If you need any help while contributing to GitLab:
- If you need help with a merge request or need help finding a reviewer:
- Join the community on the GitLab Community Discord and find other
contributors in the
#contribute
channel or initiate a mentor session. - For any other questions or feedback on contributing:
- Ping
@gitlab-org/community-relations/contributor-success
in a comment on your merge request or issue. - Feel free to make a new issue with the Contributor Success team sharing your experience.
- Ping
- Did you run out of compute minutes for your GitLab merge requests? Join the GitLab community forks project.