UX Department

On this page

UX Guide

The UX Guide documents our principles, approach, and perspective to the experience of GitLab. Help keep this document up to date and correct by creating merge requests.

UX Strategy

The vision of GitLab is far from finished and there are a lot of emergent properties that will allow us to simplify. We believe in iterative improvements and value aggressive change. We will get some things wrong and quickly strive to make them right. We have a long way to go, that is why we are taking big steps.

Please see the UX Strategy to view the evolving UX vision for GitLab.

UX Workflow

In general, follow the GitLab Workflow and the Engineering Workflow. Also see the Basics of GitLab development in the Developer Onboarding. See below for the workflow relevant to UX Designers and UX Researchers.

UX Designer

Creating and labelling issues

Working on issues

  1. Assigning / Taking on Issues:
    1. We try not to assign issues to people but to have people pick issues in a milestone themselves.
    2. All issues in a milestone labeled Deliverable that needs UX should be assigned to a specific designer by the kickoff. If an issue has no one assigned by kickoff, the issue will be assigned to someone.
    3. Once you have completed work on an issue and labeled it UX ready, please remain assigned. You will be the 'go-to' person for UX questions and reviews.
  2. Choose:
    1. Filter by the UX label and then choose in the following order:
      1. Has the current release's milestone
      2. Has the next release's milestone
      3. Has milestone Next 2-3 months
      4. Has milestone Next 3-6 months
      5. Has milestone Backlog
      6. Popular or with high community involvement (number of comments or upvotes)
      7. Everything else
    2. Before committing to issues, check if another UX Designer has already participated. If their latest activity on that issue was within two months and you’d still like to work on it, ask them what the status is and if you can pick it up for them. If their latest activity on that issue was more than two months ago, just let them know that you’ll be picking it up for them.
  3. Work:
    • Define the scope:
      • Product Managers and UX Designers are very closely related although they might seem different. In the problem–solution spectrum, Product is closer to the problem, UX is closer to the solution. This doesn't mean Product can't propose solutions or UX can't define the problem — it's a continuous conversation. Over-communicate with Product Managers, it's the best way to understand the problem and arrive at a solution.
      • Before coming up with any solution, discuss the scope with the Product Manager, ask questions, and define what the problem really is (often it's not what people think it is).
      • UX issues have a tendency to expand in scope. Aggressively split off new issues, ideas, and concepts into their own issues. Large issues become really challenging to drive decisions in and make progress on. If you’re ever unsure how to split apart large issues, work with the UX Lead.
      • Developers should be able to ship a product within one life cycle. If a feature is too large to ship within one release, work together to determine the best way of splitting the feature into smaller segments.
      • Bring developers into the conversation early. Ask for feedback on how to split up features while still maintaining the integrity of the UX.
      • When breaking up features into smaller parts, make sure that the end design goal is known. Giving everyone the full picture will help developers write code aimed at achieving that goal in the future.
      • Keep the issue description updated with the agreed scope, even if doesn’t impact your work. This is everyone’s responsibility. The issue description must be the Single Source Of Truth (SSOT), not the discussion or individual comments.
    • Propose solutions:
      • Add comments with your proposals. Propose one solution, not multiple alternative solutions for others to pick, as this undermines your position as a UX expert and leads to a design by committee situation. If you have a good reason to propose multiple alternative solutions make sure to explain why.
      • Wireframing, mockups, and prototyping all have their own place. You should utilize the best tool for communicating a problem/design/solution.
      • Proposals don't need to have images. Sometimes words can paint a surprisingly good picture of how an experience should feel, look, and behave.
      • Frame discussion around the problem being solved, not the designs specifically.
      • Anticipate questions that others might have and try to answer them in your proposal comments. You don’t have to explain everything, but try to communicate a bit of your rationale every time you propose something. This is particularly important when proposing changes or challenging the status quo. This reduces the feedback loop and time spent on unnecessary discussions while contributing to the credibility of the UX department, who deal with a lot of seemingly subjective issues.
      • Keep the SSOT updated with what’s already agreed upon so that everyone can know where to look. This includes images or links to your design work.
      • If you’re working with design files, follow the instructions in the GitLab Design project and regularly commit them.
      • If you are proposing a solution that will introduce a new UX paradigm, or change an existing one, there are additional steps to follow. See the 'Maintain' section below for those steps.
  4. Deliver:
    1. Once your work is complete, make sure that the SSOT is updated. This is where you should direct people when they have questions about what should be done and how.
    2. If applicable, commit all design assets and files according to the instructions in the GitLab Design project.
    3. Once UX work is completed and all feedback is addressed, remove the UX label, add the UX ready label, and:
  5. Follow through:
    1. Keep the SSOT in the description updated until the issue is closed. This applies to both text and mockups. Previous content (by a PM, for example) should be removed or archived into a separate section in the description. If the developer working on the issue ever has any questions on what they should implement, they can ask the designer to update the issue description with the design.
    2. For obvious changes, make the SSOT description update directly. You don't need to wait for consensus. Use your judgement.
    3. Make sure you remain assigned and that you’re subscribed to the issue and related merge requests. Continue to follow them, addressing any additional UX issues that come up.
    4. If you are asked to review an MR for an issue you were not assigned to, remind the author who the assigned designer is and assign to original designer for review.
  6. Maintain:
    1. If the UX work introduces or changes any of the UX standards or building blocks:
      • If applicable, create a merge request to update the UX Guide.
      • If applicable, create a merge request to update the GitLab Elements Sketch file.
      • When any of those requests are merged, add an agenda item to the next UX weekly call to inform everyone of those changes.
  7. Raise research requests:
    1. In a new issue
      • Within the CE or EE project, raise a new issue using the research template.
      • Add the label UX Research to the issue.
      • @ mention Sarah O'Donnell @sarahod and Katherine Okpara @katokpara
      • They will schedule the work accordingly.
    2. In an existing issue
      • @ mention Sarah O’Donnell @sarahod and Katherine Okpara @katokpara in the existing issue, summarizing what you need researched.
      • Add the label UX Research to the issue.
      • They will schedule the work accordingly.

UX Researcher

  1. Work with the UX department to determine what should be researched.
  2. Create a research issue:
    • Create an issue within the UX research project.
    • Label the issue with the area of GitLab you’re testing (for example, navigation) and the status of the issue (in progress).
    • Mark the issue as confidential until the research is completed so it doesn’t influence user behavior.
    • Assign the issue to yourself. You should only be assigned to an issue when you are actively working on it.
    • Add a progress checklist (a checklist of tasks you need to complete in order to complete the research) to the issue description. This makes it easier for people to understand where the research is up to.
    • Add a summary of what is being tested to the issue description, along with any related issue numbers.
  3. Conduct the research.
  4. Update the issue you created in the UX research project:
    • Document the findings and recommendations within the issue.
    • Unmark the issue within the UX research project as confidential. (In some cases the issue may need to remain confidential if sensitive information is shared. If you’re unsure of whether an issue should remain confidential, please check with Sarah O’Donnell @sarahod and Katherine Okpara @katokpara).
    • Update the status of the issue to done.
    • Remove yourself as the assignee from the issue.
  5. Inform people of your research:
    • Within the issue, encourage discussion between yourself, UX designers and product owners about which findings should be turned into issues within the GitLab CE or EE project.
    • Create the agreed, new issues within the GitLab CE or EE project. If relevant issues already exist, add your findings to the existing issue description or comments. Always link your findings back to the issue within the UX Research project.
    • Label any new issues as appropriate.
    • Close the issue within the UX Research project.
    • Add a link to the completed research within the UX Research project's ReadMe file

UX on Social Media

It is encouraged to share UX designs and insight on social media platforms such as Twitter and Dribbble.


You can contribute design-related posts to our @GitLab Twitter account by adding your tweet to our UX Design Twitter spreadsheet.

  1. Add a new row with your tweet message, a relevant link, and an optional photo.
  2. Ensure that your tweet is no more than 140 characters. If you’re including a link, ensure you have enough characters and consider using a link shortening service.
  3. The UX Lead will check the spreadsheet at the beginning of each week and schedule any tweets on Tweetdeck.
  4. Once a tweet is scheduled, the tweet will be moved to the "Scheduled" tab of the spreadsheet.


GitLab has a Dribbble team account where you can add work in progress, coming soon, and recently released works.