Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Product Development Flow

Overview & philosophy

GitLab's product mission is to consistently create products and experiences that users love and value. To deliver on this mission, it's important to have a clearly defined and repeatable flow for turning an idea into something that offers customer value. Note that it's also important to allow open source contributions at any point in the process from the wider GitLab community - these will not necessarily follow this process.

This page is an evolving description of how we expect our cross-functional development teams to work, but at the same time reflects the current process being used. All issues are expected to follow this workflow, though are not required to have passed every step on the way.

The goal is to have this page be the single source of truth, but it will take time to eliminate duplication elsewhere in the handbook; in the meantime, where there are conflicts this page takes precedence.

Because this page needs to be concise and consistent, please ensure to follow the prescribed change process.

Validation track

For new ideas where the customer problem and solution is not well understood, PMs and UXers should work together to validate new opportunities before moving to the Build track. The Validation track is an independent track from the always-moving Build track.

PMs and UXers should work together to get 1-2 months ahead, so that the Build track always has well-validated product opportunities ready to start. PMs and UXers should plan on spending roughly 50% of their time doing validation activities.

Validation cycles may not be necessary for things like bug fixes, well understood iterative improvements, minor design fixes, etc.

Opportunity Canvas

One of the primary artifacts of the validation track is the Opportunity Canvas. The Opportunity Canvas forces a lean product management philosophy to the validation track by focusing on level of confidence, hypotheses, and lessons learned as the document evolves. At completion, it serves the purpose of being a concise artifact for teams to reference to understand the user pain, the business value, and the constraints to a particular problem statement.


Validation phase 1: Validation backlog

Label: workflow::validation backlog

Every PM should maintain a backlog of potential validation opportunities. Validation opportunities may come from customers, internal stakeholders, product usage insights, support tickets, win/loss data, or other sensing mechanisms. Validation opportunities should be captured as an issue and described in customer problem language, and should avoid jumping ahead to feature/solution language.

Sometimes it can be tricky to identify a good issue for problem validation. The following situations often are good criteria:

Some items will skip the problem validation phase. In these cases the problem is well understood and has been validated in other ways. When skipping problem validation, ensure the issue description is clear with the rationale and sensing mechanisms used to skip the problem validation phase.

To queue an item in your validation backlog:

  1. Create a new issue describing the problem using the "Problem Validation" issue template in the GitLab project, applying relevant stage and group labels. If you are doing research related to an open issue/epic, consider notifying participants there of the research issue so they can participate.
  2. Once each section of the issue template has been filled out (or validated, in the case of pre-existing issues), apply the RICE formula as a prioritization mechanic and record this in the description.
  3. Apply the workflow::validation backlog label

Validation phase 2: Problem validation

Label: workflow::problem validation

Good product development starts with a well understood and clearly articulated customer problem. Once we have this, then generating solutions, developing the product experience, and launching to the market is much more effective. The danger in not starting with the problem is that you might miss out on solutions that come from deeply understanding the customer problem. A poorly defined problem statement can also cause the design and development phases to be inefficient.

You should pull items from your validation backlog in the problem validation process on a regular cadence to ensure you always have validated problems for your groups to start working on.

To run the problem validation process:

  1. PM applies the ~"workflow::problem validation" label to the associated issue; this automatically removes the ~"workflow::validation backlog" label.
  2. PM fills out an opportunity canvas to the best of their ability. Ensure the problem and persona is well articulated and add the opportunity canvas to the issue's Designs. Note that you should include content for the solution and go-to-market sections, possibly with low confidence; this section may be likely to change, but thinking it through will help clarify your thoughts.
  3. PM fills out a customer interview guide with a draft list of interview questions. You can find a good guide here.
  4. PM reviews customer interview guide and opportunity canvas with UX peers. UX Research can help craft interview questions and recruit candidates for interviews: request their help by following the UX research request process.
  5. PM and UX together conduct at least 5 interviews with target customers. Interview notes should be logged as an issue in the user interview project and labeled with relevant stages. (training video coming soon)
  6. PM and UX synthesize customer feedback using affinity mapping or other techniques.
  7. PM finalizes the opportunity canvas with the synthesized feedback.
  8. PM schedules a review of the opportunity canvas with Scott Williamson, Christie Lenneville, and the Product Director for your section. Weekly time blocks will be held. You can contact Stefanie Haynes to get your review added to one of the weekly time blocks.
  9. Once approved, move to design and solution validation phase below to begin solutioning the validated problem.

Validation phase 3: Solution Validation

Labels: workflow::design followed by workflow::solution validation

Once the customer problem is well understood, it's time to ideate and validate solutions to the problem. As always, you should be consistently moving issues forward from the backlog, to problem validation, and solution validation to ensure that there's validated problems to deliver.

Solution Validation is also relevant for APIs and other technical features that don't require a UI. Communicate these solutions using artifacts such as API docs, workflow diagrams, etc. Involve your Engineering Managers in creating and reviewing these artifacts to gain a shared understanding of the solution and receive input on feasibility.

To run the solution validation process:

  1. PM applies the ~"workflow::design" label to the associated issue, automatically removing the ~"workflow::problem validation" label.
  2. PM and UX co-create the user stories required to solve the customer problem. Story mapping is a recommended way to visualize the user stories of a new feature in a holistic way. The story map can even be annotated to indicate which user stories need to be included in each release increment. Here are some resources to help with story mapping:
    1. Agilevelocity Story Mapping 101
    2. Easyagile Building Story Maps PDF
    3. Jeff Patton Story Map Concepts PDF
    4. GitLab story map training video, slide deck
    5. GitLab example story mapping video
    1. UX ideates to create one or more concepts based on feedback from assigned stakeholders (PM, engineering, technical writers, and other peers). This ideation results in a prototype (low- or high-fidelity wireframes or an interactive UI prototype) that addresses the user stories for at least the first (and potentially subsequent) releases. UX shares the prototype with stakeholders and requests feedback.
  3. When the design is complete and the team is ready to test the solution, PM applies the ~"workflow::solution validation" label. UX and PM validate the prototype with at least 5 target users through usability testing interviews.
  4. PM updates the associated user stories and/or story map and opportunity canvas with any final changes.
  5. PM must articulate success metrics for each opportunity and ensure a plan for product instrumentation and dashboarding are in place.
  6. UX presents the design as part of the Product design process which serves as an approval to move to the build track.

At this point we have validated the problem and solution, and the issue is ready to enter the build track.

Build track

The build track is where we develop, launch, and improve validated solutions over time.

Build phase 1: Plan

Label: workflow::planning breakdown

The build track starts with PM, UX, and Engineering Managers breaking down the opportunities into well-defined issues:

  1. PM applies the workflow::planning breakdown label.
  2. PM, UX, and EM do a final review of the designs to ensure everyone understands the solution. Then, PM, UX, and EM start breaking down the implementation into smaller issues. Story mapping is a recommended technique to do this in a rapid and collaborative fashion. The resulting issues should be written by PMs in user-story-style language whenever possible: "As a (who), I want (what), so I can (why/value)." Issues should not only be about feature details, but should also establish functional, performance, documentation, and security acceptance criteria. In some cases, you need to update existing issues - if you were doing problem validation on an issue that already had a problem to solve/proposal in the issue (i.e., an older or customer-created issue), and you've come up with a new problem statement that isn't very close to the original, you should strongly consider opening a new issue for the new problem. Changing the problem statement in an issue almost always causes the discussion to become confused and may lose track of the original (potentially still valid for some users) problem statement.
  3. Using the output of story mapping, PM creates separate epics and issues for implementation. Use the feature proposal template as a guide for writing both epics and features. For issues requiring documentation changes/additions, add the documentation label. For issues requiring new or updated UI text, add the UI text label.
  4. At this point, the original validation issue can be closed as further work labeling and activity will happen on the implementation issues.
  5. EM sizes the implementation issues. Consult with your stable counterparts to estimate effort.
  6. EM works with assignees to create a Build Plan that outlines the number of MRs and responsibilities for assigned team members. EM and PM provide a focus on iteration when reviewing these plans.
  7. PM applies workflow::scheduling to allow for a buffered priority queue.
  8. PM assigns them to a specific milestone/release. Follow the product development timeline when scheduling implementation issues into milestones. Note that engineering will apply the workflow::ready for development label during the next phase, not PM.

Build phase 2: Develop & Test

Labels: workflow::ready for development, workflow::In dev (along with workflow::ready for review as queue state while waiting for maintainer), workflow::In review, workflow::blocked, workflow::verification (sub-states for verification are workflow::canary and workflow::staging)

The develop and test phase is where we build the features and test them before launch:

  1. Engineering teams move items into workflow::ready for development as they commit to them.
  2. When the milestone arrives, engineering teams execute on the scheduled work. Acceptance criteria as set forth in the issues must be met before a feature is deemed complete.
  3. In parallel with development, the PM creates release post content, collaborating with PMM on messaging and positioning
  4. Work deemed out of scope or incomplete by engineering is taken back into the plan phase for grooming and rescheduling for completion. The label workflow::planning breakdown should be reapplied.
  5. During the launch phase, the delivery team updates the validation labels as it flows through the validation process in staging and canary.
  6. Engineering/quality performs testing to ensure the feature is working as it flows through the environments
  7. PM should also conduct feature-level acceptance testing to ensure that the intended user value was, in fact, delivered.
  8. Documentation should be complete and available before proceeding to the launch phase.

Build phase 3: Launch

Labels: workflow::production

  1. Once the feature is deployed to production, the delivery team sets the workflow label to workflow::production. At this point the feature is launched.
  2. Engineering/quality/PM should validate again that the feature works for all users.
  3. PM should merge the release post content to master, which will then cause it to appear on the releases page.

Build phase 4: Improve

Label: TBD

After launch, the PM should pay close attention to product usage data and customer feedback to guide follow-on iterative improvements, until success metrics are achieved or a decision is made that the product experience is sufficient.


All substantive merge requests to this page require the following approvals before merging:

  1. VP of Product
  2. Director of User Experience

The following people need to be on the merge request to stay informed:

  1. Senior Director of Development
  2. Director of Quality