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


Are you not on the product team, but looking for information on how to get in contact with or provide information/ask questions to product managers? Please see our How to Engage guide.

The document below talks about how we do product at GitLab, not about what. For the what, see Product Direction.

If you are a product manager looking to learn our process, this document is broken into the following sections:

Other Product Handbook pages

Product Team Mission

Consistently create products and experiences that customers love and value.

Additional color:

Product Team Principles

These are core principles we believe strongly in. The goal is to build a PM system that fosters and honors these principles, in a way that works for GitLab.

  1. Hiring is Job 1. A players attract A players. Given the strategic importance of the PM role, a strong PM creates enormous leverage. We should strive to raise the average competency for the team with each new hire.
  2. Care personally & challenge directly. Employees that feel safe plus managers that coach honestly is how people do their best work. We encourage timely and actionable feedback, as well as managers that take the time to get to know their people as humans with feeling and personal lives, not just resources.
  3. Always be learning. Continuously invest in skill development, and have a growth mindset as individuals and as a team.
    • Helpful resource: Peak
  4. You’re not the customer. Talk to them. It is tempting to assume that we understand our customers, but we are often wrong. We validate our assumptions through qualitative and quantitative customer input.
  5. Start with the problem, not the solution. It is tempting to dive right into solutioning, but we are often wrong about the underlying problem. A well formed problem statement is the key to a successful project.
  6. Prioritize ruthlessly. It is better to do a few things well than many things poorly. We should focus first on what we’re best at and what our customers need most, with a preference for simplicity. Customers will tell us when we’re missing something they need, but they’re unlikely to tell us when we’re overwhelming them with unwanted features.
  7. Assume you are wrong. Human intuition is often wrong. To fight this, have a hypothesis & try to invalidate it quickly.
  8. Iterate. Leverage a fast-paced build-measure-learn feedback loop to iterate your way to a good solution, rather than trying to plan it all out up front.
  9. Be data driven. Always have success metrics, track them, and try to move them in the right direction with our actions.

Product Principles

The direction for the GitLab product is spelled out on the Direction page. This document provides lessons and heuristics on how to design changes and new features. Our iterative process is demonstrated in a blog post.

Much of our product philosophies are inspired by the Ruby on Rails doctrine of 'Rails is omakase'. I highly suggest reading these.

Enabling Collaboration

From development teams to marketing organizations, everyone needs to collaborate on digital content. Content should be open to suggestions by a wide number of potential contributors. Open contribution can be achieved by using a mergeable file format and distributed version control. The mission of GitLab is to allow everyone to collaborate on all digital content so people can cooperate effectively and achieve better results, faster.

Bringing Ideas to Reality

Ideas flow through many stages before they are realized. An idea originates in a chat discussion, an issue is created, it is planned in a sprint, coded in an IDE, committed to version control, tested by CI, code reviewed, deployed, monitored, and documented. Stitching together all these stages of the DevOps lifecycle can be done in many different ways. You can have a marketplace of proprietary apps from different suppliers or use a suite of products developed in isolation.

The Minimally Viable Change (MVC)

We only ship in a Minimally Viable Product (MVP) style. We call it Minimum Viable Change (MVC), because our business model is focused on adding additional value to our integrated product suite, instead of building separate, new products.

MVC means we start by delivering the smallest possible solution that offers value to our users. To avoid feature bloat, we rely on user research to validate whether our idea addresses a market need in a desirable way. This approach sets us up to expend the smallest possible amount of effort to build new capabilities, while learning more about how to best add additional functionality over time.

While an MVC may not have the robust functionality of a fully developed feature, it should still address fundamental user needs through a bug-free and highly usable experience. The minimally viable change should not be a broken feature.

Advantages of an MVC approach:


An MVC approach is a byproduct of our spirit of iteration. Even when not pursuing an MVC, we will encourage iteration in our own development process. That means we break problems down as small as possible, use throughput as a performance indicator, and focus on reduced cycle time. Thinking iteratively is not always intuitive, and breaking certain topics or projects down can be challenging. Here's a helpful video from our CEO with guidance on how to think more iteratively.

Avoid "Not Invented Here" Syndrome

Just because something is not invented here doesn't mean it doesn't have a perfect home within our solution. GitLab is an Open Core product and is part of the broader ecosystem of Open Source tools in the market. Every day there are new innovative tools out there that solve real-world customer problems; we should not be afraid of embedding these tools into our own products in order to solve those same problems for our customers too. Leveraging existing technology allows us to get to market much more quickly, to contribute to Open Source (and help strengthen Open Source as a whole), and allows us to focus our own people on making GitLab itself better. Building professional relationships with these tool creators also is a positive for GitLab since they may have important user perspectives around your categories.

We have achieved many successes following this approach:

There are also many more examples throughout the company where this has been successful. As a product manager you should be monitoring the world of Open Source as it relates to your area to see where new innovative tools are being developed, and not be afraid of integrating those. One thing to keep in mind, integrating could be anything from a blog post describing how the tool works together with GitLab all the way up to bundling it inside of our own installation, and this can evolve iteratively.

Convention over Configuration


We admire other convention over configuration tools like Ruby on Rails (that doctrine of which perfectly describes the value of integrated systems), Ember, and Heroku, and strive to offer the same advantages for a continuous delivery of software.

Furthermore, Ruby on Rails has been of massive influence to the Ruby community. Uplifting it, and making it more powerful and useful than ever before, for many more usecases. We want GitLab to be to Kubernetes, what Rails is to Ruby.

You should prefer choices that are well thought out and based on current best practices. Avoid unnecessary configuration. Avoid configuration to support fragile workflows.

For example, when considering whether to add a checkbox or two radio boxes, think carefully about what users really want. Most of the time, you'll find you really only need one solution, so remove the other option. When two possible choices really are necessary, the best or most common one should be the default, and the other one should be available. If the non-default choices are significantly less common, then consider taking them out of the main workflow for making decisions, by putting them behind an Advanced configuration tab, for example.

Avoid configuration completely when possible

Every configuration option in GitLab multiplies its complexity, which means the application is harder to use, harder to develop, and less friendly to users.

Requests for configuration can be a proxy for trying to support a fragile workflow. Rather than enabling bad habits and incurring product debt, effort should be spent helping customers adopt best practices.

Making features configurable is easy and lazy. It's a natural reaction to propose a big change to be configurable, as you worry it'll negatively affect certain users. However, by making a feature configurable, you've now created two problems.

Removing a configuration after it shipped and in use is much more work than not introducing it in the first place. This is because you change the behavior for customers that selected the less popular option. Adding a configuration is a one way door that should be avoided if possible. And for sure should be left out of the first iteration of a feature if at all possible. You can add it easily but removing it is hard.

Work on solutions that work for everyone, and that replace all previous solutions.

Ensure a great experience by default

GitLab should work perfectly right out of the box for most users. While it should be resisted, sometimes configuration is inevitable or preferable. Your configuration must not make that experience worse and should always get out of the way of the user.

Encouraging behavior

Convention also implies that we're encouraging our customers to do things in a certain way. A very concrete example of this is the ability to disable pipelines. We believe that our integrated solution will give a superior user experience and we're motivated to encourage this behavior. For this reason, adding a configuration to allow disabling this permanently (be that in a template or instance-wide), is something that should be avoided.

Encourage favorable behaviors by limiting configuration.

Default to ON

In addition to encouraging behavior by limiting the ability to toggle features, new features, when introduced, should default to turning things ON (if they are configurable at all - preferably they should not be), and when necessary, automatically migrate existing users/groups/projects to have the new features ON. Similarly, feature flags should be consistently ON for both and self-managed users whenever possible.

Limits should be in place to protect the system but not to "slowly try out" a feature. By limiting the usefulness of a feature right from the start the only thing you are achieving is limiting its adoption and usefuleness.

If you are going to default to OFF or limited, you must have a good, documented reason for this.

Deciding on configurations

Avoiding configurations is not always possible. When we have no choice, the secondary priority is to configure something in the GitLab interface. A configuration should only appear in a file (gitlab.rb or gitlab.yml) as a last resort.

Easy UX

Within each stage, the learning curve must be at least comparable to our best-in-class competitors, with clear, cohesive workflows, a highly usable interface, and comprehensive documentation. Our product must have an easy UX that accommodates all users.

Configuration in file

There are two major configuration files available in GitLab. Adding configurations to either should be avoided as much as possible.

When you have to add a new configuration, make sure that the features and services are on by default. Only add a configuration line to either of these configuration files if the feature or service cannot be fully disabled from the admin UI.

Be Ambitious

Many crazy, over-ambitious ideas sound like they are impossible just because no one else is doing them.

Since we have amazing engineers and a culture of shipping minimally viable changes, we are able to do a lot more 'impossible' things than others.

That's why we're shipping merge conflict resolution, why we shipped built-in CI before anyone else, why we built a better static pages solution, and why we're able to compete.

How this impacts Planning

Here at GitLab, we are an ambitious company and this means we aim for big things with every release. The reality of taking chances and planning aspirationally means that we won't always be able to deliver everything that we wanted to try in every release, and similar to our OKRs, we believe this is a good thing. We don't want to shy away from challenging ourselves and always want to keep a sense of urgency, and aiming for more helps us do that. Also see the importance of velocity

We arrived at our preference for ambitious planning after measuring our velocity and finding that our velocity was unchanged whether we scheduled ambitiously or scheduled for providing slack.


Doing something simple in GitLab should BE simple and require no human cpu-cycles to do so. Things that are simple now should still be simple two years from now, ten years from now, and onwards.

This sounds obvious, but messing with flow is easily done. In most cases, flow is disrupted by adding another action, or another click.

For instance: You want users to be made aware of the rules of a project. Your proposal is a little popup that shows the rules before they create an issue. This means that every time that someone creates an issue they need to click once before resuming their normal action. This is unacceptable. A better solution is to add a link to the issue that points the user to this.

It's very hard to maintain flow with a lot of configurations and options. In cases where you want to enforce a certain behavior, the most obvious step may be to add another step or action. This can be avoided by making the action work in parallel (like a link in the issue), encouraging rather than enforcing certain behaviors.

Also, we don't want users to be able to construct workflows that break GitLab or make it work in unpredictable ways.

Discoverability Without Being Annoying

Feature discoverability is important for allowing new and existing users to access old and new features, thereby increasing the value for them. It also allows GitLab to get as much feedback as possible, as fast as possible, in order to quickly iterate.

However, UI that purports to increase discoverability, but that is not carefully designed and implemented, may actually harm the overall experience by constantly shoving unwanted images and text in the face of the user. The end result is that the user loses trust in GitLab, and they no longer take the time to carefully parse text and other UI elements in the future. Even worse, they might leave GitLab because of this degraded experience. The following are a few illustrative examples and best practices.

Empty states



Think of this: Your co-worker is hard at work in front of their computer, and you suddenly tap their shoulder or yell at them to tell them about some new cool widget. You better have a good reason for that: that widget better be awesome.

Back to the analogy: Your co-worker said they don't care about that new cool widget. Never, ever, ever, bring it up again. They told you they don't care, and you need to respect that.


Leveraging navigation is an effective design paradigm to introduce a user to a new feature or area of GitLab.

Back to the analogy. We're not going to bother our co-worker with 5 different cool new widgets at the same time.


Flow One

Shipping only MVCs can result in a large set of loosely connected pieces that don't necessarily combine into a single, great user experience.

An obvious solution to this would be to plan out the future in detail, creating a long-term detailed plan. However, this is unwanted as it can restrict your flexibility and ability to respond to changing needs or feedback.

Flow One offers an alternative. You draw out a workflow consisting of MVCs (that can be shipped individually). The workflow should only cover a specific, narrow use-case, and nothing more.

This means you:

Flow One should cover the first iteration of a particular workflow. After this, individual MVCs can be introduced to expand the use-cases or loosen the assumptions (e.g. from a feature that can only be used if you're using feature branches, to one that works for other git strategies).

Breadth over depth

See our thoughts on breadth over depth on our strategy page. While we prioritize breadth over depth, Product Managers should not lose sight of maturing each product category, with the ultimate goal of each category moving into a lovable state. A good rule of thumb to consider when planning product improvements, is that over time, approximately 70% of engineering effort should be allocated on breadth, and 30% on depth.

Data-driven work

Using data to learn from our users is important. Our users are spread across and self-managed instances, so we have to focus our efforts on learning and providing benefit to both when we decide to collect more data, or build and use additional analytics tools. If we do this, we can help make the rest of the company successful as well. This means that we should:

No artificial limits in Core

Per GitLab Stewardship, we will not introduce artificial limits in Core. Artificial means arbitrarily setting a small number (such as: 1) as a limit on a given GitLab object category, that would incur no additional effort or cost had we chosen a larger number. The additional effort includes product, design, and engineering effort to create the feature in the first place, and to maintain it over time.

For example, GitLab Core has the issue board feature in every project. In GitLab EE, each project supports multiple boards. This does not mean that Core has an artificial limit of one board per project, because there is additional effort to manage multiple boards such as supporting the navigation interface, and all the associated engineering work.

No enforced workflows

We're discussing enforced workflows in this issue.

Enforced workflows should be avoided in GitLab. For example, there are three issue states (Open, In Progress (as of 10.2), and Closed), and any issue should be allowed to transition from one state to any other state without workflow restrictions. (Roles and permissions is a separate concern.)

A comment on Hacker News perfectly details what can go wrong when enforcing workflows:

"The down side for the true end-users, those who actually use the software day-to-day, is that most business processes are awful. If your experience is the hellish existence that I see strolled about on threads where JIRA comes up …:

  1. Your admin(s) set it up once and hasn't bothered to iterate on those workflows.
  2. The business mapped their autonomy stripping processes onto JIRA intentionally. I'd guess that most of your work experience is similar. Process stifled nonsense."

But that comment also specifies the advantage:

"JIRA's most powerful feature is that it affords for mapping businesses processes onto software. This is incredibly compelling to enterprise customers. Software that enforces workflows, procedures and requirements can be an incredible lever and JIRA's price point makes build vs buy decisions an absolute no-brainer."

We should ensure that GitLab makes it easy to help with enterprise workflows:

Prefer small primitives

Small primitives are building blocks in GitLab. They are an abstraction not at the technical level, but truly at the product level. Small primitives can be combined, built-upon further, and otherwise leveraged to create new functionality in GitLab. For example, the label lists in issue boards use the smaller primitive of labels.

They are especially powerful because they usually take less effort and provide higher leverage than you would get from a more "complete" but standalone feature. Think of how simple Unix command line utilities can be chained together to do really complicated things, much easier (and certainly more flexibly) than you could have done with a dedicated tool.

When iterating on GitLab, strongly consider using small primitives instead of creating new abstractions, especially when considering MVC features that will provide the foundations for further improvements. To do this you can start with easy to apply concepts that meet the needs of intermediate to advanced users; from here document the usage clearly and be sure to think about discoverability. The UX can very often be refactored or enhanced later when there's a demonstrated need for refinement, onboarding for less sophisticated users, or other new abstractions needed that were identified through real-world usage.

Avoid plugins and marketplaces

Closed source software vendors commonly depend on plugins and marketplaces because:

  1. These allow third parties the ability to add functionality without needing access to the underlying codebase.
  2. Third parties can charge for the plugins, which gives them an incentive to build them.

Because GitLab is an open core product, third parties can add functionality directly to GitLab. Adding directly to the GitLab codebase (as opposed to building a plugin) may mean more work for them and will limit the ways in which they can charge for that functionality.

However, for users of GitLab, this has significant advantages:

  1. They are more likely to use this functionality, because it's distributed to all users by default.
  2. The functionality always works out of the box, requiring no additional software.
  3. Users don't have to search for what plugins are available, or test multiple options to see which one works the best.
  4. Installations can't have varying combinations of plugins, making it easier to use and support the product.
  5. Administrators never have to avoid an upgrade for fear that it might break an important plugin since all code is tested together.

And for developers of GitLab including the third parties, this has significant advantages as well:

  1. Their work isn't limited in functionality, because they're changing the code of the product itself.
  2. Their code will be tested along with the rest of the product as things change refactoring is easier, reducing the likelihood that it suffers from software atrophy because something is hard to change.
  3. Community effort is not wasted on developing multiple plugins that all ultimately do the same thing and compete with eachother for usage.
  4. Developers don't have to sacrifice velocity in favor of predictability, since they don't have to worry about breaking the plugin API.

Overall, we believe that this approach creates the best possible experience for both the users of and the contributors to GitLab, and to that end we encourage people to contribute functionality to GitLab directly.

If adding code directly to GitLab isn't an option, we encourage third-parties to integrate through our APIs.

Note: GitLab does support plugins that respond to system hooks, which tie directly to application events and are primarily used for administrative purposes such as auditing, logging, and other administrative tasks.

Next Generation

While our big, hairy, audacious goal spans all development processes, personas, and use-cases, there are primary targets in each one of these venues. When considering prioritization we should first aim to provide complete maturity for developers building cloud native applications in a modern way prior to moving to other development methodologies, personas, and application types.

Modern first

When developing features to compete with existing competitors, make sure to solve problems for modern development teams first, and then see what's missing for legacy teams. e.g. For project management, make great project management capabilities for teams doing conversational development, lean, or even agile development before doing Scaled Agile Framework (SAFe) or waterfall.

Developer first

Our strategy includes going after a lot of new personas, going from developers to operations, security, product managers, designers, etc. But when developing features in these new areas, it's important to remember to start with the developer. If we can make security great for developers and then great for security professionals, we'll be much more successful.

Cloud-native first

Development teams deploy to tons of different platforms, from bare metal to cloud VMs to cloud-native Kubernetes clusters. We build features for cloud-native first, and then support the rest. This allows us to focus on where development is going, and deliver solutions that every company aspires to use eventually, even if they're not ready to today.

Prioritize Current Adopters

By focusing on next-generation development flows, personas, and use cases - we build features and experiences where our initial users are in the relatively small population of early adopters. While we might build experiences to support them today, we presume there will always be a much larger population of future users of these experiences. Therefore, we optimize GitLab to support the larger number of current and future adopters of next-generation principles - those who are beginning to operate in the workflow (modern), team setup (developer first), or application architectures (cloud native) we support. We focus our investment in the most modern workflows that will best support those current adopters. This will come at the cost of sustained investment in initial workflows for early adopters.

For example - we first provided an application log experience based on direct scraping of logs via kubectl. After adding support for installing Elasticsearch to your Kubernetes cluster, we should not continue to invest in the kubectl log view as we'd recommend newcomers to use Elasticsearch.

Product Process

Introducing changes requires a number of steps, with some overlap, that should be completed in order:

Product Manager Onboarding

Product Manager onboarding, beyond any product specific steps in your first week onboarding ticket, is defined in the Product projects PM Onboarding issue template.

Onboarding issues can be tracked in the Product Onboarding Issue Board.

Iteration on Product Management Onboarding is encouraged by all team members. To do so, create an MR against one of the above files and assign it to your manager for review and merge.

Important dates PMs should keep in mind

See Product Development Timeline.

Planning horizon

Aligned with the company cadence, Product planning follows:

  1. Mission: 30 years
  2. Vision: 10 years
  3. Strategy: 3 years
  4. Plan: 1 year
  5. Milestones: quarter (we have issues assigned to specific release milestone for a rolling 3 months)
  6. Release: month (we try to not change the release that is started)

Inspired by:

Product Development Flow

GitLab follows a dual-track product development flow spanning product, engineering, and UX.

This process should be both up front and on an on-going basis when building features.

PM, EM, and UX trio DRIs

GitLab is designed and developed in a unique way.

Consistent with our value of Efficiency the product is developed with directly responsible individuals from Product, UX, and Engineering working together.

Product Managers Engineering Managers UXers
Set priorities and define what Engineering works on Own the definition of done; decide what gets merged into Product Proactively identify small and large strategic UX needs to aid Product Management prioritization

GitLab PMs aren't the arbiters of community contributions

PMs are the DRI for what GitLab Engineering team members work on. As a result contributions from the wider community and from other teams in GitLab are not subject to the processes described below nor are they prioritized by GitLab Product Managers. So long as an MR matches the definition of done, changes may make their way into Product.

Managing your Product Direction

The product direction is an important part of each PMs work. PMs are expected to maintain the accuracy of their plan throughout the year through stakeholder conversations and other research. Your product direction is displayed as the direction labeled issues for your group's categories which are displayed in the Section, Stage, and Category direction pages of our website.

Around November, we begin the annual planning cycle, which ties closely into the overall strategy. During this period we update the direction label and apply it to issues that have been identified as contributing to the plan that year.

PMs are able to refine their plans and strategy throughout the year, but since the these are important to be aware of, major updates to the content that happen ad-hoc should also be communicated widely - for example, using the Product FGC meetings or other communication channels.

What makes a Product Direction issue?

It's important to note here that your plan is not simply a list of new features and innovation. Those are included for sure, but so are issues related to all of your sensing mechanisms.

A category upgrade from minimal to viable or delivery of a top customer issue (for example) can contribute to your plan just as much as a brilliant new innovative feature can. It's up to PMs to balance this through a coherent longer-term strategy.

Conversely, in a broad sense anything could move the plan forward in a general way. Product Direction items (i.e., with the label) should be direction-level items that move the strategy forward meaningfully. This is up to the PM to set the bar for, but there should be a clear step forward with real user value.

Finally, issues are the substance of your plan. Epics can receive the label as well, to keep things organized, but we track the delivery of our plan on a per-issue basis. Ensure you are applying the label appropriately.

Moving the product direction forward

In each release, you should be moving your plan forward. At least one item with this label should be included; if not, it's possible you're getting off track from where you planned to go and should assess.

Note that, by their nature, Product Direction items should not be sitting in the backlog or with no milestone. If they are this is a signal that either they are not as important as originally thought, or that something important is not getting due attention.

Prioritization: Ahead of kickoff

  1. Proper discovery has been done and requirements for the change are defined
  2. Engineering has been involved in the discovery process (FE, BE, UX, as needed)
  3. Technical architecture has been drafted and is agreed upon
  4. Scoping and splitting up into actionable issues has happened
  5. Issues that move your plan forward have the appropriate Product Direction label applied

Kickoff meetings

The purpose of our kickoff is to communicate with our community (both internal and external) a view of what improvements are being planned in the coming release. This can help other GitLab teams, community contributors and customers gain an understanding of what we are prioritizing and excited to deliver in our next iteration.

While kickoffs are commonly used to ensure visibility of work across an internal audience, our connection to a broader community and commitment to transparency means we also serve an external audience.

The process for preparing and presenting group and company wide Kickoff meetings is outlined in our Monthly Kickoff issue template. We create an issue from that template each month to collaborate on that month's Kickoff.


  1. Design
  2. Backend development
  3. Frontend development
  4. QA and feature assurance
  5. Deploy

Content of an MVC

Here are some guidelines to follow when exploring an MVC:


Virtually every new feature must be maintained forever (the standard for sunsetting a feature is very high). Creating a new feature means that GitLab has to continually manage the costs of maintaining that feature. Making small changes with quick feedback loops reduces the risk of introducing a new feature where the value doesn't justify the long-term costs.

A new feature also adds a tax on the user experience due to additional complexity in the product. Make sure that the benefits gained by users from the new feature more than cover the tax incurred, accounting for how frequently the new feature will be used. In particular, the new feature should satisfy this inequality:

(benefits * frequency) / (tax * (1-frequency)) > 1

Despite its minimal form, the change

Quickly converting ideas into MVCs

There is a certain failure case for MVC issues that product managers need to be aware of and actively work to prevent. Because we don't have infinite capacity to work on everything and good ideas are always coming in, it's possible (if the PM is not watching closely) for issues with good ideas to slowly but inevitably decay into something that is difficult to understand and move forward with.

As more and more comments are added, the issue slowly morphs from idea to idea without any direction from a product manager. Then, it becomes difficult to ever make complete sense of it again without losing some important context. It's also nearly impossible for someone who wants to make a community contribution to understand what the direction is. In other words, it becomes an undefined blob of ideas.

To prevent this, it is the product manager's responsibility to quickly determine whether an open-ended issue aligns with our business model and is broadly useful. If the answer to those questions is "yes," then we must turn it into something actionable, deliverable, and truly MVC as quickly as possible. If the answer is “no,” then we must close the issue to maintain our backlog’s hygiene.

The guidance for product managers is to never let an idea issue persist longer than three months without having been converted into a clear MVC. If this has not happened, you should ask yourself why this is the case: Is the idea overly broad? Is there no clear immediate deliverable? Is it just not important enough to spend time on? These are all signals that should be acted on without delay, before the issue degrades to the point that it becomes unusable without significant rework.

In practice, if the original issue was really broad and still contains great ideas, then simply converting it into an MVC that gets closed when it ships could be a disservice, because you lose valuable context when it's time to improve the MVC. In this case, consider creating a new issue for the MVC, so that it is crisp and concise, and leave the original issue as a post-MVC meta item.

QA RCs on staging and elsewhere

After the feature freeze, it's expected of each product manager to test their own features and perform quality assurance to the best of their ability and follow up where necessary.

Product managers can use the staging environment once the release managers have deployed a release candidate to staging. Release managers should post in the #product channel in Slack that a new release candidate is available. Product managers can also use other environments as needed, such as GitLab provisioned on Kubernetes with GKE.

Feature assurance

Before a new feature is shipped, the PM should test it out to make sure it solves the original problem effectively. This is not about quality assurance (QA), as developers are responsible for the quality of their code. This is about feature assurance (FA). FA is necessary because sometimes there are misunderstandings between the original issue proposal and the final implementation. Sometimes features don't actually solve the intended problem, even though it seemed like it would, and sometimes solutions just don't feel as useful as intended when actually implemented.

If you can test out the feature during development, pulling down branches locally (or with a review app!), that's great. But sometimes it's not feasible to test a feature until it's bundled into a release candidate and deployed to If so, make sure to test out features as soon as possible so any new issues can be addressed before final release. Also, take the FA cycle into account when scheduling new milestone work.

If you are looking to test code that has not been merged to or is not yet part of an RC, you can pull the branch down locally and test it using the GitLab Development Kit (GDK).

Dealing with security issues

Product managers should set Milestones for issues marked with the security label to guarantee they are shipped by their due date, as defined in the Security Team process. Product Managers are the DRIs for prioritization. As such they should deeply understand the implications and risks of security related issues and balance those when prioritizing. You may need to set a different milestone for security issues, for example because of low capacity, but before doing that you should engage a conversation with the Security Team. Priority labels and Due Date designations should not be modified by product managers in any case, since they are directly managed by the Security Team, and used to track metrics and progress.

Cross-stage features

Each Stage is responsible for building functionality that is core to their value. Even if some components of that functionality happen to cross in to spaces typically owned by other stages, they should still build it (if it's important to them).

If the feature isn't necessary or urgently needed to move forward (for example, it won't block another feature's development), then you can always consider putting it on the backlog of the stage that owns that feature.

Here are some guidelines for thinking about "Which stage should do this work?":

  1. If a stage wants to develop new functionality that is core to their value, even if it happens to live inside a feature owned by another stage, they should still build it.
  2. Alternately, if the functionality lives inside another stage's feature, but is also very-much a "nice-to-have", they should consider putting it in an issue and labeling it appropriately. This way, the stage that owns that feature can prioritize it at a later date when it makes sense for them to do so.
  3. External requests for integration with 3rd party systems will be handled by the Ecosystem group by default. But again, if the feature is core to a stage's value proposition, they should go ahead and build it themselves.

This model allows teams to be flexible and calibrate their priorities accordingly, and no team should ever be "blocked". Exceptions may be items where a change requires anything that a software engineer would not be allowed to do, such as a production change, in which case the infrastructure team would be the blocker.

While any team can contribute features to any stage, it is recommended to loop in the most relevant PM from that Group to provide strategic support to help the contributing team align to the Group's broader plan and vision.

Stages, Groups, and Categories

Stages, groups, and categories serve as a common framework for organizing and communicating the scope of GitLab.

Making changes to stages, groups, or categories

Documentation on how to make changes to stages, groups, and categories, as well as what approvals are required, can be found in our website handbook page.

Managing creation of new groups, stages, and categories

After a change has been approved, we may need to globally optimize during the initial transition period, and ensure that important issues are not blocked.

There are three common scenarios we may encounter during these transition periods:

In each of these scenarios, a Group may become temporarily responsible for a future Group's issues and backlog. During this time, the responsible Group should balance the needs of our users and organization, prioritizing across the common backlog.

Splitting a Stage into multiple Groups

As the group(s) working on a Stage grow in size, a new Group may need to be formed so group sizes remain manageable. For example, today there is a single group for Manage, but will be splitting into control and framework groups.

To prepare for splitting a Stage into multiple Groups, we should:

  1. Update categories.yml and stages.yml, assigning each Group a set of Categories
  2. Ensure all issues remain labelled with the Stage name, like devops::manage
  3. Ensure all issues also have a group label, like Control or Framework
  4. Prior to the new groups being formed, the PM and EM prioritize the shared devops::manage backlog

Once the first PM or EM is hired, the new Group should be formed:

  1. The other PM/EM's will need to continue working across both Groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both Groups until additional hires are made.
  2. EM's and engineers should work together and divide the existing engineering team to staff the new groups, like Control and Framework. Ideally, each group would have at least two backend engineers, but that is not always possible.
  3. Update stages.yml and team.yml to reflect the current group members. You may need to add a member to the end of _categories.erb.
  4. Create a Slack channel for each group, like g_control and g_framework, and close the previous Slack channel (e.g. g_manage)

As the rest of the EM/PM's are hired, they take over that role for the respective group.

Adding a new category to a Stage

The categories within a Stage will change over time, based on GitLab's direction and the market landscape. The groups within a Stage will need to be able to handle these changes, without issues falling in the cracks.

When the categories change, we should:

  1. Update categories.yml and stages.yml, ensure all categories are assigned to a Group
  2. If two categories are merging, apply the new category label to issues from both of the old categories
  3. If a new category is being added, create a new category label and apply it to relevant issues
  4. Update category vision to reflect the new labels and categories
  5. Review the handbook and other material which may link to old categories
  6. Remove old category labels
Adding a new Stage

When GitLab decides to address additional needs within the single application, a new Stage may need to be created. For example, Defend may be created to address additional needs beyond what Secure focuses on.

When a new Stage is added, and its Group has yet to be formed, we should:

  1. Ensure all issues for the new Stage are assigned with the Stage labels, like devops::defend and Defend
  2. Identify an existing Group, like Secure, which will be initially responsible for the new Stage
  3. The existing Group will prioritize across a common backlog of both Stages, in this example devops::defend and devops::secure
  4. Update categories.yml and stages.yml, listing the new Stage with the members of the existing responsible Group. Update _categories.erb with the member name if necessary.

Once the first PM or EM is hired, a new Group for the Stage should be formed:

  1. The other PM/EM's will need to continue working across both groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both groups until additional hires are made.
  2. EM's and engineers should work together to staff the new Group, like Defend. Each Group should have at least two backend engineers.
  3. Now that the new Group is formed, both Groups can focus on their respective Stages. In this case, Secure on Secure and Defend on Defend.
  4. Update stages.yml to reflect the new Group and its members. Update _categories.erb with the member name, if necessary.

As the rest of the EM/PM's are hired, they take over that role for the new Group.

Product support requests

Throughout the customer lifecycle, customer facing teams (Support, Sales, Professional Services, Account Managers, etc.) may need the assistance of a product manager. This can include a detailed discussion of our direction, how to address specific use cases, or gaps in functionality, with an organization.

To ensure these requests can be quickly triaged, easily scheduled, and later tracked, there is a standardized request process based on issues.

Requesting support from Product

Product support requests are tracked in the Product team project. To create a request:

  1. Create a new issue with the Product-Support-Request template
  2. Fill out the form within the template, be sure to include relevant details and issues
  3. Ensure the issue is confidential, save it.

For time sensitive and high impact requests, please paste a link to the issue in the #product Slack channel, and @mention the recommended PM's in the template.

Working with support requests

When a support request is opened, labels will automatically be assigned to categorize the request.

Three fields are particularly important when triaging requests:

All product managers should ensure they are set up to receive label notifications for their respective stages:

  1. List the product project's labels
  2. Subscribe to relevant the stage labels.

Product Management Career Development Framework

IC Title PM Sr. PM Principal PM  
Manager Title     Group Manager PM Director PM
Discovery Track Skills Adept at qualitative customer interviewing. Familiar with prioritization frameworks like RICE to organize opportunity backlogs. Capable of deriving key insights and patterns from customer interviews, and using that input to clarify problem statements. Proficient at story mapping, to break epics down into smaller MVC issues. Proficient at collaborating with Design on protoypes to bring potential solutions to life. Skilled at qualitative customer interviewing. Excellent at deriving key insights and patterns from customer interviews, and using that input to clarify problem statements. Skilled at story mapping, to break epics down into smaller MVC issues. Excellent at collaborating with Design on protoypes to bring potential solutions to life. Skilled at qualitative customer interviewing. Skilled at story mapping, to break epics down into smaller MVC issues. Capable of teaching product discovery techniques to others. Ensures consistent execution of discovery track skills across a large team.
Build Track Skills Adept at breaking epics and issues down into MVC's. Knowledgeable about GitLab's product and the relevant product domain(s). Knowledgeable about GitLab's architecture, API's, and tech stack. Capable of running a demo anytime. Able to make highly informed prioritization & tradeoff decisions with engineering. Able to discuss & evaluate technical architecture recommendations from eng. Responsible for the health of working relationships with peers in the Group. Familar and comfortable with agile development methodologies. Excellent at breaking epics and issues down into MVC's. Deep familiarity with GitLab's product and the relevant product domain(s). Deep understanding of GitLab's architecture and tech stack. Able to elevate performance of the Group through excellent PM outputs. Expert at breaking epics and issues down into MVC's. Expert in the relevant product domain(s) and capable of teaching others about the domain. Responsible for the health of working relationships with fellow Engineering Managers. Ensures consistent execution of build track skills across a large team. Responsible for the health of working relationships with fellow Engineering Directors.
Business Skills Understands and communicates the business value of epics and issues. Sets success metrics for epics and issues, and tracks metrics post-launch to guide investment in iterative improvements. Spends up to 20% of time researching & defining category vision & strategy. Able to ensure activities are consistent with GitLab's go-to-market and business model. Can balance build, buy and partner options for solving customer problems. Can identify new market opportunities & author business cases, as well as forecast the approximate benefits of new features. Spends up to 30% of time researching & defining category vision & strategy. Expert at business case creation. Capable of managing business results across a range of product domains. Works cross-stage and cross-functionally to ensure an excellent end-to-end customer experience. Excellent at understanding and managing the business impact across a wide range of product domains. Capable of making key pricing & packaging recommendations.
Communication Skills Capable written and verbal communicator internally and externally. Drives clarity in area. Trusted resource for customer calls and meetings. Builds rapport with stakeholders to align around priorities. Self aware and understands how their interactions impact others. Takes action to improve behavior based on impact to others. Capable of representing GitLab externally at trade shows, customer events, conferences, etc. Solid presentation skills at all levels of the company. Appropriately influences & persuade others to a course of action. Recognized as a thought leader internally and externally. Excellent presentation skills at all levels of the company. Escalates issues cleanly to appropriate levels of authority when decisions or progress are blocked. Visible leader across teams. Establishes compelling team purpose that is aligned to the overall organizational vision. Inspires broader team to achieve results. Identifies disconnects to vision and takes appropriate action.
People Management Skills N/A N/A Aligns team with larger Stage vision and goals. Translates and aligns strategy in a meaningful way for team, building a shared understanding of team goals and targets. Uses situational leadership techniques to provide appropriate level of guidance and latitude to team members. Proactively identifies and fills talent gaps. Adept at caring personally for team members and providing candid real-time feedback. Aligns team with larger Section vision and goals. Provides appropriate level of guidance and latitude to managers and individuals. Experienced at hiring and at managing out underperformance. Excellent at caring personally for team members and providing candid real-time feedback.
Typical Reporting Structure Reports to a Director or Group Manager Reports to a Director or Group Manager Reports to a Director or VP Reports to VP
Typical Experience Two to four years of relevant experience or equivalent combination of experience and education. Four to six years of relevant experience or equivalent combination of experience and education. Eight to ten years of experience with at least one year of people management responsibility. Ten to twelve years of experience with at least four years of people management responsibility.

Interviewing Product Management Candidates

A unique and important step in the interview process for Product Management candidates is our Deep Dive Interview. The goal of this interview is to understand the candidate's ability to communicate a long term vision as well as a short term MVC, both verbally during the interview itself, and written via two follow up issues. Once the issues are ready for you to read, it is an opportunity to provide feedback and see how the candidate responds to that feedback.

You can find more information and instructions on the Deep Dive interview here. For information on our hiring process, head over to our hiring handbook pages.

How to work as a PM

If you follow the principles and workflow above, you won't be writing long, detailed specs for a part of the product for next year. So how should you be spending your time?

Invest the majority of your time (say 70%) in deeply understanding the problem. Then spend 10% of your time writing the spec for the first iteration only and handling comments, and use the remaining 20% to work on promoting it.

A problem you understand well should always have a (seemingly) simple or obvious solution. Reduce it to its simplest form (see above) and only ship that.

Once you've shipped your solution, both you and the community will have a much better idea of what can be improved and what should be prioritized for future iterations.

As a PM, you're the person that has to kick-off new initiatives. You're not responsible for shipping something on time, but you are responsible for taking action and setting the direction. Be active everywhere, over-communicate, and sell the things you think are important to the rest of the team and community.

As a PM, you need to set the bar for engineering. That is, to push engineering and the rest of the company. You almost want engineering to complain about the pace that product is setting. Our default instinct will be to slow down, but we can't give in to that.

As a PM you don't own the product; ask other people for feedback and give team members and the community the space to suggest and create things without your direct intervention. It's your job to make sure things are decided and planned, not come up with every idea or change.

Where should you look when you need help?

Responsibilities and Expectations

The responsibilities for Product Managers, Sr. Product Managers, and Principal Product Managers, Group Manager, Product Management Director of Product, VP of Product and VP of Product Strategy are outlined in our job families pages.

The progression of responsibilities allocation between tactical, operational and strategic is well illustrated by this helpful chart.

GitLab PM Responsibility Allocation Chart

Source File. Note - Thanks to Melissa Perri for the inspiration

In addition, as a Product Manager you're expected to:

Occasionally, Product Managers are asked to perform the role of "Life Support" Product Manager for a group. When doing so please refer to the Life Support PM expectations.

As we grow, Product Managers can be listed across multiple stages and be asked to perform the role of Product Manager across split or multiple teams in an "Interim" basis. While temporary and based on future hiring, these positions are not considered "Life Support" and thus the standard Responsibilities and Expectations apply.

Scope of responsibilities

The product team is responsible for iteration on most of GitLab's products and projects:

This includes the entire stack and all its facets. The product team needs to weigh and prioritize not only bugs, features, regressions, performance, but also architectural changes and other changes required for ensuring GitLab's excellence.

Key Performance Indicators (KPIs)

The list of Product KPIs are here and the definitions are here.

Objectives and Key Results (OKRs)

Like all teams, the Product team participates in GitLab OKRs. The Product team OKRs are tracked as issues in the Product project.

The process for doing so is:

Long Term Financial Success Criteria for

The Product team is responsible for the direction and financial measurement of the strategy but does not carry direct P&L responsibility. Long term financial success for is measured as:


As this document and the direction page shows, there are a million things we want to do. So, how do we prioritize them and schedule things properly? Roughly speaking, we balance the following priorities:

Priority Description Issue label(s)
1 Security fixes security
2 Data-loss prevention data loss
3 Availability availability
4 Fixing regressions (things that worked before) regression
5 Velocity of new features, user experience improvements, technical debt, community contributions, and all other improvements feature, enhancement, technical debt
6 Behaviors that yield higher predictability (because this inevitably slows us down) predictability

Please also note the corresponding Engineering handbook section about the relative importance and prioritization of availability, security, and feature velocity. To ensure we're providing an appropriate focus on security, data loss, and availability, PMs should consider:

Using the RICE Framework

RICE is a useful framework for prioritization that can help you stack rank your issues. The RICE framework is a great tool for prioritizing many issues that seem to be of equal value at first glance. In order to drive clarity and alignment in the prioritization of work across the entire DevOps platform, and to help prioritize items that may compete for resources from different teams, we have set a standard for the RICE factors so all prioritization decisions based on RICE are using the same metric.

Reach How many customers will benefit in the first quarter after launch? Data sources to estimate this might include qualitative customer interviews, customer requests through Support/CS/Sales, upvotes on issues, surveys, etc.

Higher reach means a higher RICE score:

Impact How much will this impact customers? Impact could take the form of increased revenue, decreased risk, decreased cost, which makes it possible to compare revenue generating opportunities vs. non-revenue generating opportunities.

Higher impact means a higher RICE score:

Confidence How well do we understand the customer problem? How well do we understand the solution and implementation details? Higher confidence means a higher RICE score.

Effort How many person months do we estimate this will take to build? Lower effort means a higher RICE score.

Calculating RICE Score

These four factors can then be used to calculate a RICE score via the formula:

(Reach x Impact x Confidence) / Effort = RICE

Here is an example RICE calculation you can use to help prioritize work in your area. Feel free to embed this at the Epic level to provide context for why you did or did not prioritize.

RICE Factor Estimated Value
Reach 1,000
Impact .5
Confidence 80%
Effort 2 month
Score (1,000 x .5 x .80) / 2 = 200

Other important considerations:

We schedule a prioritized issue by assigning it a milestone; for more on this see Planning a Future Release.

Issues important to customers

For prioritizing most issues, we should utilize the RICE framework noted above, which will capture an aggregate of customer demand.

In some cases however, we may become aware of a feature which is particularly important to deliver on by a certain date. Examples of this could include an issue necessary to embark on a new GitLab rollout, a feature needed by a partner to launch an integration, or a method to import data from a service which is being discontinued. In these instances, the responsible PM can apply the planning priority label along with a due date and initial milestone. This label can serve to indicate externally that the issue is particularly important, as well as a reminder for internal teams of its importance.

Issues with the planning priority label should be:

It is important to note that the planning priority label does not constitute a promise for the issue to be delivered in any given milestone or timeframe.

Community Considerations

GitLab is open-source, and while PMs aren't the arbiters of community contributions, encouraging and promoting a large ecosystem of contributors is critical to our success. When making prioritization decisions, it's important to heavily weight activities which will encourage a stronger community of contributors. Some of those activities are:

Product managers are not responsible for prioritizing contributions outside of their group. These contributions should be reviewed and merged swiftly allowing everyone to contribute, including non-product teams at GitLab.

Working with Your Group

As a product manager, you will be assigned as the stable counterpart to a single group. At GitLab we abide by unique, and extremely beneficial guidelines when interacting with our groups. These include:

  1. Product Managers are the DRI for all prioritization within their group including bug fixes, security issues, feature, tech debt, and discovery. They alone determine and communicate priority. The process for doing so is documented and standard across all groups.
  2. Product Managers provide the what and when, Engineering (UX, Backend, Frontend, Quality) provide the how. This process is documented as part of our monthly product, engineering and UX cadence. We define stable counterparts for each of these functions within a group.

As an all-remote company, our crispness when it comes to responsibilities throughout the Product Delivery process was born out of necessity, but it pays untold dividends. Some of the benefits include:

User Experience (UX)

As the GitLab product matures, we know we must make important workflows easier to use. As part of this effort, the UX department is collaborating with Product Management to select highly used workflows in stable areas of the product. We'll assess and score these workflows using the UX Scorecards methodology and then work together to prioritize recommended improvements.

This effort aligns with the Category Maturity goals that move areas of our product from minimal to viable to complete and, finally, lovable.

From Prioritization to Execution

As described above, prioritization is a multi-faceted problem. In order to translate the priorities of any given group into action by our engineering teams, we need to be able to translate this multi-faceted problem into a flat list of priorities for at least the next release cycle. Product Managers are responsible for taking all these prioritization considerations and creating a clear, sequenced list of next priorities. This list should be represented as an issue board so that each team has a clear interface for making decisions about work. From this list, UXers, Engineering Managers and Product Managers can work together to determine what items will be selected for work in the immediate future.

This does not mean that items will be addressed in strict order - UXers, EMs and PMs need to be cognizant of dependencies, available skillsets, and the rock/pebbles/sand problem of time management to make the best decisions about selecting work.

Reviewing Build Plans

Together with your Engineering Manager, you will have an important role in ensuring that the Build Plans defined for issues are created with iteration in mind. Iteration is highly valuable for the following reasons:

  1. It can result in discovering ways to parallelize effort, resulting in less team WIP and increase throughput
  2. It can result in shipping something of value during an iteration rather then delaying everything
  3. It can re-risk unknown unknowns by bringing them to light sooner in the development process

Prioritizing for Predictability

As a company we emphasize velocity over predictability. As a product manager this means you focus on prioritizing, not scheduling issues. Your engineering stable counterparts are responsible for velocity and delivery. However, there are instances when there is desire for predictability, including:

As the DRI for prioritization, it is the Product Manager's job to prioritize for predictability when it is needed. You should do so by ensuring you prioritize a deliverable, and its dependencies, so that it can reasonably be expected to be delivered by any committed dates. If there is time pressure to hit a date, the PM should also explore de-scoping the issue to meet the deadline, rather than pressuring engineering to move abnormally fast or cut corners.

Headcount Resets

Individual product managers must consider, and advocate for global optimizations within the teams they are assigned to. If your assigned team requires expertise (remember everyone can contribute) outside the team you should make all reasonable efforts to proceed forward without the hard dependency while advocating within the product management team for increased prioritization of your now soft dependencies.

If you have a request for additional help within your group, it is your responsibility to advocate for it. It's important to avoid generic "we need another Developer in X group" statements. Instead, create an issue which includes a concrete list of critical issues for no more than the next three months (example).

These issues should all be considered "top priority" and generally fall in one of the following three categories:

Include your proposal for other issues and groups outside of your own which should be considered a lower priority. Once you've reviewed the issue with your assigned Engineering Manager - ping your Product and Engineering Directors for review and refinement. If a global optimization which spans beyond your Department leaders is required, then the Senior Director of Engineering, VP of Product, and VP of Engineering should be pinged.

Please note: this now called a "Headcount Reset" because it shifts team members from one team to another, and can have signficant opportunity costs. Taking people who are familiar with a task and putting them on a new, unfamiliar task instead of new hires (who are also not familiar with the task) is inefficient.

Exit Plan

The following exit plan is an initial attempt to spell out when and how the loaned engineers will be released to their original teams. A new hire is expected to be brought up to speed in this context. The plan will be iterated and amended as necessary.

Week 1 is the first week a new hire joins the team.

Phase Timeline (recommendation) What happens Notes
Onboarding Week 1 ~ 3 On-loan engineer works full-time on receiving team to bring up new hire. New hire's first week priority is onboarding.
Collaboration Week 4 ~ 5 On-loan engineer works half-time on receiving team while new hire is able to submit MRs of low complexity issues. On-loan engineer's time may be dedicated completely in pair programming or code review, not necessarily making direct contribution to issues.
Handoff Week 6 ~ 8 New hire is now the owner. On-loan engineer transitions to a consultant role, reverting back to full-time in original team.  

Private tools and dashboards for monitoring and KPI tracking

These information sources may be useful to help you prioritize.

Managing creation of new groups, stages, and categories

As GitLab grows we will need to create new groups, stages, and categories. During this transition period we need to globally optimize, and ensure that important issues are not blocked during the creation of a new group.

There are three common scenarios which may encounter these transition periods:

In each of these scenarios, a Group may become temporarily responsible for a future Group's issues and backlog. During this time, the responsible Group should balance the needs of our users and organization, prioritizing across the common backlog.

For every scenario above, we also need to ensure that the Engineering Metrics dashboard is updated to correctly track the new label. The label change affects both Issues and Merge Requests. The Stage and Group labels power the visualization and metrics in the Quality and GitLab Insights dashboards. Please create a new issue in the Triage Ops with the template

Splitting a Stage into multiple Groups

As the group(s) working on a Stage grow in size, a new Group may need to be formed so group sizes remain manageable. For example, today there is a single group for Manage, but will be splitting into control and framework groups.

To prepare for splitting a Stage into multiple Groups, we should:

  1. Update categories.yml and stages.yml, assigning each Group a set of Categories
  2. Ensure all issues remain labelled with the Stage name, like devops::manage
  3. Ensure all issues also have a group label, like Control or Framework
  4. Create a "Label change" issue in Triage Ops listing affected label to have the change reflected retroactively in Engineering Dashboards.
  5. Prior to the new groups being formed, the PM and EM prioritize the shared devops::manage backlog

Once the first PM or EM is hired, the new Group should be formed:

  1. The other PM/EM's will need to continue working across both Groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both Groups until additional hires are made.
  2. EM's and engineers should work together and divide the existing engineering team to staff the new groups, like Control and Framework. Ideally, each group would have at least two backend engineers, but that is not always possible.
  3. Update stages.yml and team.yml to reflect the current group members. Update _categories.erb with the member names, if necessary.
  4. Create a Slack channel for each group, like g_control and g_framework, and close the previous Slack channel (e.g. g_manage)

As the rest of the EM/PM's are hired, they take over that role for the respective group.

Adding a new category to a Stage

The categories within a Stage will change over time, based on GitLab's direction and the market landscape. The groups within a Stage will need to be able to handle these changes, without issues falling in the cracks.

When the categories change, we should:

  1. Update categories.yml and stages.yml, ensure all categories are assigned to a Group
  2. If two categories are merging, apply the new category label to issues from both of the old categories
  3. If a new category is being added, create a new category label and apply it to relevant issues
  4. Create a "Label change" issue in Triage Ops listing affected label to have the change reflected retroactively in Engineering Dashboards.
  5. Update category strategy to reflect the new labels and categories
  6. Review the handbook and other material which may link to old categories
  7. Archive old category labels, this will be done by the Quality Department as part of the "Label change" issue.

Adding a new Stage

When GitLab decides to address additional needs within the single application, a new Stage may need to be created. For example, Defend may be created to address additional needs beyond what Secure focuses on.

When a new Stage is added, and its Group has yet to be formed, we should:

  1. Ensure all issues for the new Stage are assigned with the Stage labels, like devops::defend and Defend
  2. Create a "Label change" issue in Triage Ops listing affected label to have the change reflected retroactively in Engineering Dashboards.
  3. Identify an existing Group, like Secure, which will be initially responsible for the new Stage
  4. The existing Group will prioritize across a common backlog of both Stages, in this example devops::defend and devops::secure
  5. Update categories.yml and stages.yml, listing the new Stage with the members of the existing responsible Group. Update _categories.erb with the member name, if necessary.

Once the first PM or EM is hired, a new Group for the Stage should be formed:

  1. The other PM/EM's will need to continue working across both groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both groups until additional hires are made.
  2. EM's and engineers should work together to staff the new Group, like Defend. Each Group should have at least two backend engineers.
  3. Now that the new Group is formed, both Groups can focus on their respective Stages. In this case, Secure on Secure and Defend on Defend.
  4. Update stages.yml to reflect the new Group and its members. Update _categories.erb with the member name, if necessary.

As the rest of the EM/PM's are hired, they take over that role for the new Group.

Planning and Direction

As a PM, you must plan for the near term milestones (more detailed) as well as for the long term strategy (more broad), and everything in between. Considered as a spectrum, these form a nearsighted roadmap. This will enable you to efficiently communicate both internally and externally how the team is planning to deliver on the product vision.

Communicating dates

Use calendar year (CY) dates for your issues, milestones, and labels to communicate timelines. Fiscal year (FY) does not translate well outside the company and roadmaps and vision pages are intended for external consumption. If you'd like to denote that an issue will be completed within a fiscal quarter use the month or GitLab release number for the last month in the fiscal quarter. E.g. use 12.4 (2018-10-22) instead of FY20-Q3. The issue can always be moved up in date and users/customers will seldom complain when functionality ships earlier than expected.

Planning is indispensable but don't follow the plan

Creating a thoughtful direction for your section, stage, or category is a useful thought exercise that can help focus efforts, aid in prioritization, and get large groups of people on the same page. But beware of simply executing your long term plan. Our industry is incredibly dynamic, and we learn new things every day that can and should cause us to re-think our long term plans. Stay focused on creating value each and every milestone, and be quick to adjust your longer term plans as you learn more.

Section and Stage Direction

Section leaders are responsible for maintaining Direction pages that lay out the strategy and plan for their respective section and stages. The direction pages should include topics outlined in this template, which include:

Category Direction

A category strategy is required which should outline various information about the category including overall strategy, what's next, and the competitive landscape. The category strategy should be documented in a handbook page, which allows for version control of the category strategy as well as the ability to embed video assets. One of the most important pieces of information to include in the category strategy is a tangible next step or MVC in order to push the category up the category maturity curve.

When creating a category strategy, it's important to focus your time and attention on specific actions and future iterations. It's natural to want to spend significant effort predicting the future, but iteration is one of our primary values. Your category strategies should contain short paragraphs with lots of references to specific issues. Here is an example.

We use this category strategy template as the outline for creating the handbook pages. If additional headings are needed you are empowered to create and populate them in your category strategy. You must keep these categories in sync with categories.yml and for new categories.

For categories that have already shipped, and that have a marketing product page, categories.yml should link to the product page, and the product page should then have a link to the category strategy (you can see an example for GitLab Pages with a Strategy button here). You should also link to your category strategy from your stage strategy page.

Maturity Plans

For each category, we track the improvements required to advance to the next level of maturity. These issues are indicated with an epic, and the planned feature set should be clearly visible from the corresponding category strategy page. e.g.:

The category epic should include:

For specifics of how the category strategy page should look, see the category strategy template.

Next three milestones

In order to plan effectively around releases, as a PM you should have 3 months of detailed milestones scheduled at all times. The issues contained in these milestones are the ones you should be spending the most energy on (fleshing them out, adding detail, discussing, etc). These issues will go through a refinement period where Product, Engineering, UX, and other parties will discuss the proposal until a proper MVC proposal is reached (see Content of an MVC for more detail). Most of the communication should happen within the issue comments, but some may happen offline (such as via Slack). Ensure that any relevant information that arise as part of an offline conversation is added to the issue title and issue description. As a PM you must ensure that issues have enough detail added to them before they become actionable as part of an iteration.

These next milestones will also help planning for capacity with engineering and UX in order to commit to the contents of the next release.

Sensing Mechanisms

Our ability to iterate quickly is a measure of our efficiency, but our effectiveness is just as critical. As a product manager you are critical to us not just working correctly, but working on the correct things. You do that by prioritizing appropriately. Your prioritization decisions will be enhanced if you maintain a sufficient understanding of the context in which you make them.

There is no limit to the amount of inputs you can utilize for making prioritization decisions. We've organized these mechanisms into three lists. One for those that primarily sense feedback from users, one that primarily senses feedback from buyers and another that senses internally generated feedback which could represent buyers or users. For new PMs consider these lists as guidance for places to ensure you are plugged in to maintain sufficient context.




Managing Upcoming Releases

Refer to the Product Development Timeline for details on how Product works with UX and Engineering to schedule and work on issues in upcoming releases.

Planning for Future Releases

Product Managers assign milestones to issues to indicate when an issue is likely to be scheduled and worked on. As we consider more distant milestones, the certainty of the scope of their assigned issues and their implementation timelines is increasingly vague. In particular, issues may be moved to another project, disassembled, or merged with other issues over time as they bounce between different milestones.

The milestone of an issue can be changed at any moment. The current assigned milestone reflects the current planning, so if the plan changes, the milestone should be updated as soon as possible to reflect the changed plan. We make sure to do this ahead of starting work on a release. Capacity is discussed between the PMs and the engineering managers.

In general, closer-to-current-time milestones are assigned to issues that are higher priority. It's best to maintain prioritization of your groups issues using a fully prioritized issue board. The timing of prioritized items broken across releases reflects an approximate product direction, with more distant milestones reflecting increasing uncertainty.

The milestones are:

These assigned milestones should be used as a signal for GitLab stakeholders and collaborators, to help them with their own respective workflows.

In addition, we have two special milestones: Backlog and Awaiting further demand. Product Managers assign these issues to milestones that they have reviewed and make sense, but do not fit within the upcoming release milestones due to either a lack of comparative urgency or because we have not yet seen enough user demand to prioritize the item yet. The best way to demonstrate urgency on either of these items is to vote on them and, if possible, add comments explaining your use case and why this is important to you.

Recommendation for when to change 'Awaiting further demand': Consider the number of people who use, not just have access to, the area impacted by the issue. When you receive enough feedback to be equal to a percentage of the power users, it is likely to consider moving the issue forward. Often public feedback only comes from a small percentage of people using or evaluating a feature or product. There needs to be a balance between waiting too long and acting too fast. In addition, there may be a tendency for more negative feedback than positive feedback, remember that people are passionate enough to care about this issue and it should be taken constructively.

Recommendation when changing a previously planned issue to Backlog: When moving a previously planned issue to Backlog, especially one planned for within the next release or two, consider the message that this may be sending to parties that were interested in this feature. In some cases, they may have been depending or planning upon the issue to be delivered around the assigned milestone, and with the change to Backlog that is now unlikely to occur. In these instances, it is best to concisely explain the rationale behind the change in a comment, so the community can understand and potentially respond with additional justification or context. It is also encouraged to move the issue to the Backlog as soon as it is clear that it will not be scheduled in the near future. This will help with understanding the change, as it will not seem like a last minute change.

Again, the milestone of an issue can be changed at any moment, including for both of these special milestones.

For a detailed timeline, see the product development timeline.

Shifting commitment mid-iteration

From time to time, there may be circumstances that change the ability for a team to ship the features/issues they committed to at the beginning of the iteration. These steps also apply when an issue is broken into multiple issues. When this happens, as a PM you must ensure the impacted issues and their milestones are updated to reflect the new reality (for example, remove deliverable tag, update milestone, etc.). Additionally, notify your manager of the shift.

Utilizing our design system to work autonomously

Our design system provides the means to work autonomously, without always needing UX insight and feedback. When problems can be solved using an already documented paradigm, you don't need to wait for UX approval to bring an issue to a reasonable state within a first iteration.

If lingering questions remain, subsequent iterations can address any shortcomings the feature might have.

Introducing a breaking change in a minor release

As a product manager, you should carefully consider the costs and benefits when planning to introduce a breaking change. Breaking changes may heavily impact existing users, and it is your responsibility to minimize the negative effects.

If you want to introduce an urgent breaking change in a minor release (e.g. you need to provide support for a new feature that cannot be backward compatible), you have to consider how many users will be affected by the change, and whether the change can wait until the next major release instead.

If you evaluate that the impact on users is acceptable (e.g., you have evidence that the feature is not used significantly), and the change will allow many users to benefit of new features or to solve problems, follow this process:

  1. Create an issue to discuss the breaking change, describing it in detail including the impact and benefits.
  2. Consider if you really need to do a breaking change in a minor. Can you wait for the next major release?
  3. Communicate the breaking change as soon as possible, for example:
    • Publish a blog post about the upcoming change, with a timeline and a simple way to recognize who is affected, and who is not
    • Ask to schedule tweets about the blog post in the #twitter Slack channel
    • Ask to reach out customers that may be affected by the change in the #customer-success and #sales Slack channels
    • Mention the problems customers may report and how to address them in the #support_self-managed and #support_gitlab-com Slack channels
  4. Throughout this process, think like a customer. Figure out actions that could make the breaking change less painful from their point of view.
  5. Always keep the issue up-to-date.

Community participation

Engaging directly with the community of users is an important part of a PM's job. We encourage participation and active response alongside GitLab's Community Advocates.


A general list of conferences the company is participating in can be found on our corporate marketing project.

There are a few notable conferences that we would typically always send PMs to:

If you're interested in attending, check out the issue in the corporate marketing site and volunteer there, or reach out to your manager if you don't see it listed yet.


Internal and external evangelization

Before shipping a new or updated feature, you are responsible for championing it, both internally and externally. When something is released, the following teams need to be aware of it as they will all need to do something about it:

You can promote your work in several ways:

Working with Product Marketing (PMM)

Product marketers and managers should be joined at the hip. Just as a feature without documentation should not be considered shipped, benefits of GitLab that we're not actively talking about might as well not exist.

Product marketers rely on product managers to be guided to what is important and high impact. In general, you should:

Marketing materials

As a PM you're responsible for making sure changes you've shipped are well represented throughout GitLab's documentation and marketing materials. This means that on release, features.yml is updated, documentation is merged and deployed, and any existing content is updated where necessary.

It's not acceptable to do this after the release. GitLab is very complex, and features and functions are easily missed, even those that provide significant value to customers (e.g. the many ways you can authenticate with GitLab).

You can recruit the help of the marketing and technical writing team if needed, but it's highly recommended to do small updates yourself. This takes less time and overhead than communicating what needs to be done to someone else.

Major feature rollout

Major features deserve proper attention from Product and Marketing. With a proper rollout, we'll have ample marketing opportunities and receive more feedback ahead of, during, and after the release.

Here is the ideal rollout schedule. For each step there is an indication for who is responsible for it.

  1. Feature is drafted in an issue (PM)
  2. Feature is planned in an upcoming release (PM)
  3. A feature proposal blog post is made (PM or Dev), which includes:
    • What we are planning on doing.
    • How people will be able to get it: CE or any EE Editions.
    • A link to the issue.
    • When it'll be available, if possible.
    • Anything else that is interesting to share in order to fuel the discussion.
  4. Feature is implemented, and documentation is written (Dev).
  5. Feature should appear on the website (Marketing)
    • For very significant features: Feature page on the website is made and pushed, with the mention "Available from X.X"
    • For other features: Feature should be listed on some page (/devops-tools, Enterprise page, /features page).
  6. Feature is launched with the release (Marketing)
    • "Available from X.X" is removed
    • Documentation and other resources are linked
    • Pricing page is updated if needed
  7. Feature is highlighted in a blog post (Marketing)
    • This post is linked from the feature page on the website (if applicable)

Release posts

As a PM, you are accountable for adding new features (under your umbrella) to the monthly release post, respecting the guidelines defined in the release posts handbook and its due dates. Be sure to go over all the details.

Every month, a PM will take the leadership of the release post, and will be responsible for delivering it in time.

Writing release blog posts

For every monthly release, there is a blog post announcing features. The blog post should contain everything exciting or disruptive. All new features should appear in the blog post. We want to help people understand exciting features (which are often new), and increase adoption. Disruptive features may significantly improve workflows or occasionally introduce unavoidable inconveniences. We want to anticipate questions and avoid confusion by communicating these changes through the blog post. UX improvements that significantly adjust current workflow should be included. Smaller tweaks and bug fixes don't necessarily need to be mentioned, but if interesting, can be included at the bottom of the post.

Including epics

One situation that can happen is that an epic contains many small issues that don't individually meet the bar for the direction label, and therefore inclusion in the release post. More rarely, the last issue of an MVC that took several releases isn't necessarily a capstone issue on its own. If you find yourself in a situation where you have closed an epic during a release, you should also ensure that we communicate that as a combined entity in a feature block, even if there is otherwise no single issue to mention.

Writing about features

As PM we need to constantly write about the features we ship: in a blog post, internally to promote something, and in emails sent to customers.

While we want every PM to have a unique voice and style, there are some guidelines that one should take into account when writing about features. Let's highlight them with a concrete example, Preventing Secrets in your repositories, that we shipped in 8.12.

It's a bad idea to commit secrets (such as keys and certificates) to your repositories: they'll be cloned to the machines of anyone that has access to the repository. If just a single one is insecure, the information will be compromised. Unfortunately, it can happen quite easily. You write git commit -am 'quickfix' && git push and suddenly you've committed files that were meant to stay local!

GitLab now has a new push rule that will prevent commits with secrets from entering the repository.

Just check the checkbox in the repository settings, under push rules and GitLab will prevent common unsafe files such as .pem and .key from being committed.

Recording videos to showcase features

In addition to the written medium, video is an important medium that caters to a different learning style. Depending on the type of video you are recording, there are some guidelines to keep in mind.

Speed Run: Informal video meant to focus on a single workflow and the experience for performing that workflow. It should not require much planning and is typically short in duration (less than 5 min.). This video type is meant to inform and not necessarily to influence buyers.

See the Remove docker images via CI/CD speed run video for an example.

Walk-through: Informal video meant to focus on cohesiveness across categories and workflows. Requires a bit more planning than a speed run but doesn't require high production value. These are typically longer in length as they cover more ground.

See the Auto DevOps setup and usage walk-through video for an example.

Demo: Scripted recording meant to influence buyers. Generally has higher production value and typically involves both a slide-style presentation and/or live screen-sharing. Duration varies depending on the topics being covered.

See the GitLab for the Enterprise Demo video for an example.

Stakeholder Management

Updated SSOT for stakeholder collaboration

Stakeholder collaboration and feedback is a critical competitive advantage here at GitLab. To ensure this is possible, and facilitate collaboration, you should maintain an updated single source of truth (SSOT) of your stage direction, category strategies, and plan, at all times. This equips anyone who wants to contribute to your stage’s product direction with the latest information in order to effectively collaborate. Some sections and teams use the scheduled Direction Update issue template to remind themselves of this task.

Actively and regularly reach out to stakeholders. Encourage them to view and collaborate on these artifacts via these (non-exhaustive) opportunities:

Here is some guidance for new PMs to ensure your stage direction, category strategies and plan are up-to-date and visible to critical stakeholders:

Customer meetings

It's important to get direct feedback from our customers on things we've built, are building, or should be building. Some opportunities to do that will arise during sales support meetings. As a PM you should also have dedicated customer discovery meetings with customers and prospects to better understand their pain points.

As a PM you should facilitate opportunities for your engineering group to hear directly from customers too. Try to schedule customer meetings at times that are friendly to your group, invite them, and send them the recording and notes.

Sales Support Meetings

Before the meeting, ensure the Sales lead on the account has provided you with sufficient background documentation to ensure a customer doesn't have to repeat information they've already provided to GitLab.

During the meeting, spend most of your time listening and obtaining information. It's not your job to sell GitLab, but it should be obvious when it's the time to give more information about our products.

For message consistency purposes, utilize the Value Drivers framework when posing questions and soliciting information.

After the meeting, make sure all your notes and feedback land in issues.

Customer Discovery Meetings

Customer discovery meetings aren't UX Research. Target them to broad-based needs and plan tradeoff discussions, not specific feature review. There are two primary techniques for targeting those topics:

Set up a meeting by identifying what you're interested in learning and prepare appropriately. You can find information about how customers are using GitLab through Sales and Sales and support should also be able to bring you into contact with customers. There is no formal internal process to schedule a customer meeting, but if the need arises, we can formulate one.

During and after spend most of your time listening and documenting information. Listen for pain points. Listen for delightful moments. Listen for frustrations. Write down your findings in GitLab issues. Read back and review what you've written down with the customer to ensure you've captured it correctly.

After the meeting make sure all your notes and feedback land in appropriate issues. Make appropriate adjustments to category strategies, feature epics, and personas. Share your findings with your fellow product managers and the sales and customer success account teams for the customer.

You can find some additional guidance on conducting Customer Discovery Meetings from these resources:

Sourcing Customers

While sales is a great partner in sourcing customer meetings, you don't have to wait for these to take place before reaching out to customers. You can use the following techniques to source customers:

GitLab Solution Architects know our customers the best, especially from a technical perspective.

GitLab Issues customers will often comments on issues, especially when the problem described by the issue is a problem they are experiencing firsthand. The best strategy is to capture their feedback directly on the issue, however, there are times when this is not possible or simply doesn't happen. You can find alternative contact info by clicking on the user's handle to see their GitLab user page; this page often includes contact information such as Twitter or LinkedIn.

Zendesk is a great tool to find users who are actively making use of a feature and either came across a question or an issue. The best way to request a chat is through the support ticket, however, you can also click on the user that initiated the interaction and their contact information will display on the left hand side panel.

If you don't have a Zendesk account, see how to request a light agent Zendesk account.

Social Media can also be effective. If your personal account has a reasonable number of connections/followers, you can post your desire to connect with users on a specific question directly. When posting, remember to include the subject you want to discuss as well as how people can reach out.


If you want to reach a wider audience, consider asking a community advocate to re-post using the official GitLab account for the relevant platform. You can reach advocates on the #community-advocates Slack channel.

Non-users are often more important than GitLab users. They can provide the necessary critical view to come up with ideas that might turn them into GitLab users in the end. The best non-users are the ones who don't even plan on switching to GitLab. You can reach these people at local meetups, conferences or online groups like, Hacker News. In every such case, you should not try to interview the user on spot, instead organize a separate meeting where nobody will be distracted, and both of you can arrive prepared.

Customer Advisory Board Meetings

One specific, recurring opportunity to get direct feedback from highly engaged customers is the GitLab DevOps Customer Advisory Board. You may be asked by the CAB to present your stage at these meetings. Here are some guidelines when doing so:

Working with (customer) feature proposals

When someone requests a particular feature, it is the duty of the PM to investigate and understand the need for this change. This means you focus on what is the problem that the proposed solution tries to solve. Doing this often allows you to find that:

  1. An existing solution already exists within GitLab
  2. Or: a better or more elegant solution exists

Do not take a feature request and just implement it. It is your job to find the underlying use case and address that in an elegant way that is orthogonal to existing functionality.

This prevents us from building an overly complex application.

Take this into consideration even when getting feedback or requests from colleagues. As a PM you are ultimately responsible for the quality of the solutions you ship, make sure they're the (first iteration of the) best possible solution.

Competition Channel

When someone posts information in the #competition channel that warrants creating an issue and/or a change in features.yml, follow this procedure:

How and when to reject a feature request

Rejecting a feature request or a merge request is not an easy thing. People can feel quite protective of their ideas. They might have invested a lot of time and energy in writing those ideas. You can be tempted to accept a feature only to avoid hurting the people who thought of it. Even Worse, if you reject an idea too harshly, you might discourage other people to contribute, which is something we should strive to avoid.

However, as the number of issues and merge requests grows incessantly, we should be diligent about rejecting features we are sure will not work out. It's better for everyone: for the product team, so we don't maintain a huge backlog of things we will never do anyway, and for the users who won't have to wait for our feedback indefinitely.

Note: it's fine to not respond to issues that we think have potential until they gather momentum.

Feature requests and merge requests can be rejected for the following reasons:

Don't forget to thank the authors for the time and effort taken to submit the feature request/merge request. In all cases and without exception, you should be nice and polite when interacting with users and customers.

Analyst Engagement

Part of being a product manager at GitLab is maintaining engagement with analysts, culminating in various analyst reports that are applicable to your stage. In order to ensure that this is successful and our products are rated correctly in the analyst scorecards, we follow a few guidelines:

It's important to be closely connected with your product marketing partner, since they own the overall engagement. That said, product has a key role to play and should be in the driver's seat for putting your stage's best foot forward in the responses/discussions.

Internal customers

Product managers should take advantage of the internal customers that their stage may have, and use them to better understand what they are really using, what they need and what they think is important to have in order to replace other products and use GitLab for all their flows.

We want to meet with our internal customers on a regular basis, setting up recurring calls (e.g., every two weeks) and to invite them to share their feedback.

This is a mutual collaboration, so we also want to keep them up to date with the new features that we release, and help them to adopt all our own features.

Dogfood everything

The best way to understand the pain that users experience with our product is to experience it for yourself. Avoid dogfooding antipatterns.

As a PM, you should actively use every feature, or at minimum the ones for which you are responsible. All of them. That includes features that are not directly in GitLab's UI but require server configuration.

If you, as a PM, can't understand the documentation, or if you struggle to install something, would anyone else bother to do it? This hands-on experience is not only beneficial for understanding what the pain points are, but it also helps you understand what can be enhanced, such as a better optimized workflow.

As a Product function, it is our responsibility to ensure that the entire company dogfoods our product. We do this by:

  1. Maintaining a set of internal stakeholders who represent GitLab team members who use GitLab for the purposes of developing and operating GitLab and
  2. Including top internal customer issues in the relevant category epics when they align with our market strategy.

Working with internal stakeholders comes with the added benefit of getting immediate feedback that reduces cycle times and de-risks early investments in new categories and features. Beyond feature velocity, internal dogfooding saves the money that we would spend on third-party tools.

Internal users can help quickly identify where workflows might break down or where potential usability or performance issues must be explored. We should heavily weigh internal feedback to shape our perspective on customer needs, and then compare it to what we know about both large and small customers (and if we’re unsure, then we should proactively ask).

Dogfooding Process

Follow this process to make sure deliberate Dogfooding decisions are made by the PM responsible for a given DevOps Stage and memorialized. It is okay to resolve an urgent problem if GitLab does not provide certain functionality. Just follow this process after to see if something needs to be rebuilt.

  1. Create an issue in the gitlab-org group labeled Dogfooding and spur a discussion with PM. This label should never be removed so the decision making process gets memorialized on the Dogfooding board.
  2. PMs must make an explicit decision and apply an appropriate label:
    1. Dogfooding::Rebuild in GitLab: For existing work that was already built outside GitLab that needs to be rebuilt
    2. Dogfooding::Build in GitLab: For new issues that should be built into GitLab
    3. Dogfooding::Keep Outside GitLab: For issues that it's okay to build outside GitLab because they don't align with product vision
    4. Dogfooding::Use Existing Feature: To capture work to consume and use existing, unused feature in GitLab by an internal customer
  3. If the decision is to Build or Rebuild in GitLab, PMs will provide an estimate of when a feature can be delivered. Internal customers should be prepared to contribute to that effort in order to accelerate delivery.
  4. A good rule of thumb when considering effort to build in GitLab compared to building a tool outside is to use the '5x' rule. The '5x' rule states that if the effort to build the tool inside of GitLab is less than five times the effort to build it outside of GitLab, you should choose to build it inside of GitLab.

Here is a board that visualizes all the Dogfooding scoped labels.

Check out this 10 minute discussion about dogfooding:

Example: configuring GitLab

Most of GitLab is configured through the file gitlab.rb. It's tempting to add a new parameter in this file - it's easy, fast to do, and won't require adding a new UI element to allow the configuration of this new setting. However, changing this file requires you to reconfigure GitLab. To do that, you have to login to your server and type in commands to reconfigure your instance, possibly multiple times if you have more than one server.

This is not something that we can ask our customers to do. Only by using your own product and features will you realize that some practices should be avoided as much as possible.

Roadmaps, Boards, Issues & Epics


You should strive to maintain an updated Epic roadmap for your group (here's an example). This can take considerable effort but doing so will ensure your issues are well organized according to the principals laid out below.


As part of our planning process it is important that you maintain a prioritized issue board for your group. It's customary to call these boards STAGE - GROUP - Planning and to configure them to filter to all issues with your group label and with each milestone as a column (here's an example).

As the DRI for prioritization it is your responsibility to ensure that all items on your Planning board are scheduled to a milestone and are prioritized both within and across milestones. This means the lowest priority in the current milestone would generally be the top priority in the next milestone.

In this regard your planning exercise is a complete prioritization of the near term issues.


Issues related to the same feature should be bundled together into an into an epic.

Epics for a single iteration

Features may include multiple issues even if we are just targeting an MVC. In this case, we should use an epic to collect all of them in one single place. This epic should have a start and an end date, and it should not span more than 3 releases, otherwise we run the risk of having epics drag on indefinitely.

When these issues are finished and closed, we should have successfully achieved the epic's goal. A good example of this kind of epic is the first iteration on a new feature. Epics representing MVCs should clearly state MVC at the end of the title and should have a parent epic relationship towards a category strategy or a meta epic.

Meta epics for longer term items

We use epics to track many issues related to a specific topic, even if there isn't a specific timeline for shipping. These epics should be marked as ~meta, they may not have a specific start or end date, and may contain single iteration epics.

This is useful to have an overview of the future so participants and observers can understand how the pieces fit together. It can be really useful to understand the context of where we think we’re going so we can do a good job with the MVC.

Also, it conveys confidence internally and externally that we understand what we need to do when the MVC is particularly minimal. But don't get too caught up in long-term epics as you risk making proposals too complex, and overrepresenting certainty in the solution. Don't work too far in the future; we'll know better once we ship something small.

When creating a meta epic, there's a natural tendency to capture it as quickly as possible and then move on, but we must always strive to create a more specific epic for the first iteration, or the next iteration if something already exists. Describing an MVC means that the community can contribute more easily. Also, after distilling things down to a first iteration, you might realize it’s a lot easier than you thought, and prioritize it earlier. You can have an MVC without a meta issue. But you can't have a meta issue without an MVC.


We use issues to define narrowly scoped items of work to be done. Issues can focus on a variety of different topics: UX problems, implementation requirements, tech debt, bugs, etc.

A good guideline for experience-related issues is that they should address no more than one user story. If an issue includes multiple user stories, then it is likely an epic.

When to create an issue

You should create an issue if:

You should consider not creating an issue when:

Issue state

When an issue is open, this signals that we're intending or considering implementing that change. It's important to close issues that we're not considering implementing in the near future, so that we avoid creating uncertainty with customers and colleagues.

When closing an issue for this reason, make sure to update the issue body and leave a comment explaining why the issue is being closed. Issues can be reopened if we change our stance on them.

Prioritizing older issues

Sometimes, you'll end up prioritizing an issue that was created a significant time ago. When you move these issues into an upcoming milestone, look closely to see if they need to be groomed again, so that they include current information. A good rule is to review any issue you didn't personally create or that has been open longer than 3 months.

When to close an issue

To clearly communicate to our stakeholders what we are going to do, it's critical that you not only provide the positive view (what we will do), but also articulate the negative view (what we will not do). While this should be communicated in stage and category strategies, it starts with issues:

As a Product Manager you should close issues that are:

  1. Duplicated elsewhere.
  2. No longer relevant due to other reasons.
  3. 'Not the next iteration': an iteration on a proposed feature that is unlikely to ship in the next few months.
  4. 'Won't do': An issue that we have no intention of implementing, because it does not fit within or is antithetical to our vision, it presents a security risk, or other reasons you outline in the issue.

When closing an issue, leave a comment explaining why you're closing the issue, and link to anything of relevance (the other duplicate, the original feature that this is an iteration on, etc).

The 'not the next iteration' issues are the most important ones to resolve. It is very easy to create a large, comprehensive change with meta issues and lots of improvements, but it is essential that we iterate and ship the minimum viable change. We have to ship the iteration, wait for it to be used, and ask for feedback. As a product manager, you must think about the bigger picture when making a proposal to improve the product. It's important to avoid writing this down as a bunch of issues. Come up with a direction, but only record the first step. This way we can preserve the efficiency of our value of iteration. Closing issues whenever possible is an important part of your job and helps to keep a clear view of what is next. Consider using the following template to close an issue:

Closing this because XXX is something we should do first. When that feature is finished, we can learn from observing it in use. If we learn that this issue is still relevant, we can then reopen it. See /handbook/product/#when-to-create-or-close-an-issue for more detail about this policy.

How to submit a new issue
  1. If you have time, the first thing you should do is search the GitLab project to see if a similar issue already exists. We shouldn't create duplicates if we can avoid them.
  2. Identify if the issue is about GitLab Community Edition (CE) or GitLab Enterprise Edition (EE), although this can easily be changed later.
  3. The title should highlight the wished change (or target state), not the initial problem. If you don't know the wished change yet, then it's ok to have the title reflect the initial problem to solve, but before release the issue title should be updated to reflect the wished change.
  4. The body should clearly state what the current pain point is and why it's important to solve.
  5. The initial issue should be about the problem we are solving. If a separate product discovery issue is needed for additional research and design work, it will be created by a PM or UX person.
  6. If the body contains too many paragraphs, it can surely be rewritten to be shorter.
  7. Do not use acronyms or abbreviations. Everyone should be able to jump on the issue and participate without needing a glossary.
  8. Choose labels which are relevant to the issue. If you are unsure about what certain labels are for, check the labels page), and read the descriptions. The issues workflow doc provides a breakdown of the label types and how to choose the right label.
  9. Unless you know what you are doing, do not
    • assign someone to the issue
    • assign a milestone
    • set a due date
    • add weight - weight represents the technical complexity and should be defined by our developers
  10. Mention the different stakeholders in the body of your issue. In most product related issues, we usually mention the product manager, the design, frontend, and backend managers as appropriate. Some teams have experts or liaisons that can be mentioned instead of the managers. Mentioning the people in the body of the issue will trigger the notification mechanisms chosen by the people who are mentioned - therefore there is no need to notify people in another channel after the issue has been created (Slack, email).

Product Discovery Issues

A discovery issue is intended for UX, PM, FE, and BE to discuss the problem and potential solutions. Doing product discovery without the full team is generally not an effective approach. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone.

When a product discovery step is needed to design a feature, PMs should create a separate issue (linked to the epic and implementation issue) for that research and design work to occur. We should not repurpose or otherwise reuse the existing implementation issue; doing so creates a risk of the issue being closed when the design work is complete and thereby losing track of the actual delivery of the item.

It's also important to ensure that product discovery issue is really even needed. It's possible in many situations to simply use the initial ticket for any design discussions - this will ensure all of the back and forth is in one place, avoiding the risk of losing track of parts of the discussion. If you find you are creating a issue simply to reserve time or people for execution, consider trying to secure the capacity in another way.

Be sure to follow the contribution guidelines on correct labeling practices for the product discovery label.


When relevant, you can include a wireframe in your issue to illustrate what you're thinking about. But you don't need to create wireframes on your own; our UX team has a designer embedded in every stage group who will help you figure out how to solve the problem you're addressing. They should actively participate in your planning processes, so your request won't be a surprise.

If you do want to create a wireframe, we like Balsamiq for its simplicity and low fidelity. If you are struggling for inspiration, you can also paste screenshots of similar features in other products.

Long-lasting issues

A general guideline is that an issue should only span one release. If we know an issue is going to span multiple releases, split it up into multiple issues.

Epic issues are the exception to this rule, but should be kept to a minimum and only serve to guide broader subjects, not a single feature over multiple releases. This is to make sure we stick to our values of the minimally viable change. This means that feature issues should be closed after the first iteration whenever possible. We'll know more in the future and this keeps any remaining issues short and actionable.

In addition, it's often a good idea to throw away an original plan and start fresh. Try to do this more often, even more than you're comfortable with. Close the issue and create a new one.

Which issue should you be working on?

When you don't have any specific tasks assigned, you should work on issues that are labeled Product work, in both the EE and CE projects. These are issues that need our attention the most.

Life Support PM Expectations

When performing the role of Life Support PM only the following are expected:

Some discouraged responsibilities:

Team Meetings

Weekly Product Management Meeting

There is a weekly product management meeting open to any GitLab team-member. The structure of the meeting is as follows:

  1. We review a GoogleDoc (internal only) with Agenda items in the order in which they appear in the meeting. The VP of Product will prioritize the Agenda items in advance of the meeting. The Zoom Link and meeting time are in the GoogleDoc.
  2. We take notes on the discussion
  3. We move the agenda items to date on which they were discussed

If you are a Product team member and are unable to attend the call you may add items for READ-ONLY to the agenda.

If you would like to join the call to discuss a specific agenda topic, please add it and any relevant context in advance of the meeting.

Weekly Product Leadership Meeting

The VP of Product and their direct reports track our highest priority Product Team initiatives in the Product Leadership Issue Board. In order to maintain strategic focus, there is a WIP limit of 6 for Product Leadership items with the Doing label. The VP of Product uses this board to ensure we are progressing key initiatives. If one of those initiatives needs to be discussed synchronously the assigned individual should add it to the meeting's GoogleDoc agenda. Directors can delegate and coordinate cross-product initiatives as needed based on the issues in this board.

As part of this Product Leadership Meeting we also review progress towards our OKRs.

Non-public items for discussion should be added directly to the agenda document for the meeting.

Product Manager Buddy System

In order to avoid suffering in silence, encourage growth in your trade and foster collaboration and understanding across groups and stages we have a Product Buddy System whereby we designate pairs of Product Managers. These pairs should consider working together on:

The pairing for this buddy system is defined in the Product Buddy System Google Doc (internal only).

MVC and New Config Reviews

Product Managers are fully empowered to define the what and priority of what they are building. Making PMs the DRI enables our entire company to iterate faster and drive more value for users. There are two instances where it is helpful to have an outside review of your scheduled issues. Those are:

As a result, the Ops and CI/CD sections utilize an MVC & New Config issue to encourage additional review of upcoming issues that are MVCs or introduce new configuration.

Build vs "Buy"

As a Product Manager you may need to make a decision on whether GitLab should engineer a solution to a particular problem, or use off the shelf software to address the need.

First, consider whether our users share a similar need and if it's part of GitLab's scope. If so, strongly consider building as a feature in GitLab:

If the need is specific to GitLab, and will not be built into the product, consider a few guidelines:

If after evaluating these considerations buying a commercial solution is the best path forward:

  1. Consider who owns the outcome, as the spend will be allocated to their department. Get their approval on the proposed plan.
  2. Have the owning party open a finance issue using the vendor_contracts template, ensure the justification above is included in the request.

Evaluating Open Source Software

When considering open source software in build vs. "buy" decisions we utilize the following general criteria to decide whether to integrate a piece of software:

GitLab as a Product

Single application

We believe that a single application for the DevOps lifecycle based on convention over configuration offers a superior user experience. The advantage can be quoted from the Wikipedia page for convention over configuration: "decrease the number of decisions that developers need to make, gaining simplicity, and not necessarily losing flexibility". In GitLab you only have to specify unconventional aspects of your workflow. The happy path is frictionless from planning to monitoring.

We're doubling down on our product for concurrent DevOps which brings the entire lifecycle into one application and lets everyone contribute. We are leaning into what our customers have told us they love: our single application strategy, our pace of iteration, and our deep focus on users.

Consider opportunities to take advantage of this unique attribute in early iterations. Integrating features with different parts of the application can increase the adoption of early iterations. Other advantages:

Although not every feature needs to be integrated with other parts of the application, you should consider if there are unique or powerful benefits for integrating the feature more deeply in the second or third iteration. runs GitLab Enterprise Edition.

To keep our code easy to maintain and to make sure everyone reaps the benefits of all our efforts, we will not separate codebase from the Enterprise Edition codebase.

To avoid complexity, tiers and GitLab self-managed tiers strive to match 1:1.

Since we are not able to give admin access and do not yet have full feature parity between self-managed instances and, we avoid saying that there is a one to one match between subscription levels and tiers in marketing materials. This has been a source of confusion in the past for customers. subscription scope and tiers subscriptions work on a namespace basis, which can mean:

This means that group-level features are only available on the group namespace.

Public projects get Gold for free. Public groups do not get Gold for free. Because:

Admittedly, this is complex and can be confusing for product managers when implementing features. Ideas to simplify this are welcome (but note that making personal namespaces equal to groups is not one of them, as that introduces other issues).

Keep in mind that the CEO is the DRI for pricing and tiers. This includes any changes that directly impacts how we charge customers under our licensing model, such as a change to how we handle active users. Please review the entirety of the stewardship and pricing pages before making any determinations of which tier a given feature should go in.

What goes in what paid tier

Our stewardship principles determine whether something belongs in a paid tier. The likely buyer determines which tier.

Determining the tier of a new feature

When making a decision on the tier for a new feature, please refer to the pricing page for guidance. Be sure to consider documenting your rationale for the decision in the issue description, including a reference to our stewardship page when appropriate.

Please indicate the applicable tier for an issue by applying the label associated with the tier (e.g. GitLab Core, GitLab Starter) and the Enterprise Edition label for features targeting a paid tier. Ensure this is defined before feature development begins.

Should you have any questions when making this decision, do not hesitate to collaborate with your manager, product leadership, or the CEO in the issue for clarification.

Bringing features to lower tiers

To propose bringing a feature to a lower tier, follow the process on the CEO pricing page.

Changing a price or introducing a new price

If you are considering launching a paid feature, or changing any other aspect of pricing, follow this process:

Once a final determination has been made, consider making the confidential issue non-confidential. Ensure product marketing has a related website page for the feature and price. Ensure documentation is updated to accurately portray all facets of the feature. Consider a blog post to outline the feature.

All Starter, Premium, and Ultimate features must:

Alpha, Beta, GA

Occasionally we need to test large, complex features before we are confident that we'll be able to scale, support and maintain them as they are. In this case we have the option to release them as Alpha or Beta versions.

In general, we should avoid releasing Alpha or Beta versions of features. A minimally viable change should be viable and therefore should not need a pre-release. That said, if there is a situation where we have no valid alternative, the definitions of each stage is below.

It's never acceptable to make changes that risk any damage to existing production data accessed by our users.


Closed Beta

Similar to Beta, but only available to selected users.


Generally Available (GA)

Passed the Production Readiness Review for, which means that it is:

Deprecating and removing features

Deprecating features follows a particular pattern. Use the language Deprecated or Removed to specify the state of a feature that is going to be or is removed.

Features that are deprecated or removed should be:

  1. Labelled accordingly in the documentation
  2. Labelled accordingly in the application
  3. Removed from marketing pages



Naming features

Naming new features or renaming existing features is notoriously hard and sensitive to many opinions.

Factors in picking a name



The bar for renaming existing features is extremely high, especially for long-time features with a lot of usage. Some valid but not exclusive reasons are:

Permissions in GitLab

Use this section as guidance for using existing features and developing new ones.

  1. Guests are not active contributors in private projects. They can only see, and leave comments and issues.
  2. Reporters are read-only contributors: they can't write to the repository, but can on issues.
  3. Developers are direct contributors, and have access to everything to go from idea to production, unless something has been explicitly restricted (e.g. through branch protection).
  4. Maintainers are super-developers: they are able to push to master, deploy to production. This role is often held by maintainers and engineering managers.
  5. Admin-only features can only be found in /admin. Outside of that, admins are the same as the highest possible permission (owner).
  6. Owners are essentially group-admins. They can give access to groups and have destructive capabilities.

To keep the permissions system clear and consistent we should improve our roles to match common flows instead of introducing more and more permission configurations on each resource.

For big instances with many users, having one role for creating projects, doing code review and managing teams may be insufficient. So, in the long term, we want our permission system to explicitly cover the next roles:

  1. An owner. A role with destructive and workflow enforcing permissions.
  2. A manager. A role to keep a project running, add new team members etc.
  3. A higher development role to do code review, approve contributions, and other development related tasks.

All the above can be achieved by iteratively improving existing roles and maybe adding one more.

Documentation on permissions

Security Paradigm

You can now find our security paradigm on the Secure Strategy page.

Also see our Secure Team engineering handbook.

Statistics and performance data

Traditionally, applications only reveal valuable information about usage and performance to administrators. However, most GitLab instances only have a handful of admins and they might not sign in very often. This means interesting data is rarely seen, even though it can help to motivate teams to learn from other teams, identify issues or simply make people in the organisation aware of adoption.

To this end, performance data and usage statistics should be available to all users by default. It's equally important that this can be optionally restricted to admins-only, as laws in some countries require this, such as Germany.


GitLab is developed in English, but supports the contribution of other languages.

GitLab will always default to English. We will not infer the language / location / nationality of the user and change the language based on that. You can't safely infer user preferences from their system settings either. Technical users are used to this, usually writing software in English, even though their language in the office is different.


Fast applications are better applications. Everything from the core user experience, to building integrations and using the API is better if every query is quick, and every page loads fast. When you're building new features, performance has to be top of mind.

We must strive to make every single page fast. That means it's not acceptable for new pages to add to performance debt. When they ship, they should be fast.

You must account for all cases, from someone with a single object, to thousands of objects.

Read the handbook page relating to performance of, and note the Speed Index target shown there (read it thoroughly if you need a detailed overview of performance). Then:

You must prioritize improvements according to their impact (per the availability & performance priority labels). Pages that are visited often should be prioritized over pages that rarely have any visitors. However, if page load time approaches 4 seconds or more, they are considered no longer usable and should be fixed at the earliest opportunity.

Restriction of closed source Javascript

In addition, to meet the ethical criteria of GNU, all our javascript code on has to be free as in freedom. Read more about this on GNU's website.

Why cycle time is important

The ability to monitor, visualize and improve upon cycle time (or: time to value) is fundamental to GitLab's product. A shorter cycle time will allow you to:

When we're adding new capabilities to GitLab, we tend to focus on things that will reduce the cycle time for our customers. This is why we choose convention over configuration and why we focus on automating the entire software development lifecycle.

All friction of setting up a new project and building the pipeline of tools you need to ship any kind of software should disappear when using GitLab.

Plays well with others

We understand that not everyone will use GitLab for everything all the time, especially when first adopting GitLab. We want you to use more of GitLab because you love that part of GitLab. GitLab plays well with others, even when you use only one part of GitLab it should be a great experience.

GitLab ships with built-in integrations to many popular applications. We aspire to have the world's best integrations for Slack, JIRA, and Jenkins.

Many other applications integrate with GitLab, and we are open to adding new integrations to our technology partners page. New integrations with GitLab can vary in richness and complexity; from a simple webhook, and all the way to a Project Service.

GitLab welcomes and supports new integrations to be created to extend collaborations with other products. GitLab plays well with others by providing APIs for nearly anything you can do within GitLab. GitLab can be a provider of authentication for external applications.

There is some natural tension between GitLab being a single-application for the entire DevOps lifecycle, and our support for better user experience via integration with existing DevOps tools. We'll prioritize first our efforts to improve the single-application experience, second to enable a rich ecosystem of partners, and third to improve integration with the broader ecosystem to other tools. GitLab is open-source so this should not prohibit contributors adding integrations for anything that they are missing - as long as it fits with GitLab product vision.

If you don't have time to contribute and are a customer we'll gladly work with you to design the API addition or integration you need.

Who GitLab competes with

In pursuit of our product vision of becoming a complete platform for the entire DevOps lifecycle, delivered as a single application, GitLab will inevitably compete for user and business with other DevOps tools technologies and vendors. For clarity, GitLab publicly competes with other vendors only in categories where our product is lovable (in our maturity model). We may at times name these competitors publicly.

For all other categories, GitLab will highlight examples of tools that have functionally similar features to the features GitLab is developing, but we will not name them as explicit competitors. This does not mean that we will not be trying to acquire users or business based on those categories, but it does mean that we will not refer to those other vendors as 'competitors', as our goal is to pursue our product vision (not to specifically win against other tools or vendors where we are not yet lovable).

Changing the Product handbook

This is the Product handbook. If you (a Product team member, a GitLab team-member, or anyone else) see any typos or small copywriting errors here, consider correcting them with a merge request and merging it yourself (provided you have merge permissions to this repository), and mentioning a Product team member afterward as a courtesy so that we can thank you, since we have a bias for action and trust your judgement. If you have a larger change (or don't have merge permissions), create a merge request and mention any Product team member for further review so that we can incorporate your change (if it makes sense) as soon as possible. Please don't assign anybody to the merge request.