Development Workflow by GitLab

Streamline your development process.


Development Workflow by GitLab


This document explains the workflow for anyone working with issues in GitLab Inc. For the workflow that applies to everyone please see


  1. Start working on an issue you’re assigned to. If you’re not assigned to any issue, find the issue with the highest priority you can work on, by relevant label. You can use this query, which sorts by priority for the started milestones, and filter by the label for your team.

  2. If you need to schedule something or prioritize it, apply the appropriate labels (see Scheduling issues).

  3. If you are working on an issue that touches on areas outside of your expertise, be sure to mention someone in the other group(s) as soon as you start working on it. This allows others to give you early feedback, which should save you time in the long run.

  4. You are responsible for the issues assigned to you. This means it has to ship with the milestone it's associated with. If you are not able to do this, you have to communicate it early to your manager and other stakeholders (e.g. the product manager, other engineers working on dependent issues). In teams, the team is responsible for this (see Working in Teams). If you are uncertain, err on the side of over-communication. It's always better to communicate doubts than to wait.

  5. You (and your team, if applicable) are responsible for:

  6. Once a release candidate has been deployed to the staging environment, please verify that your changes work as intended. We have seen issues where bugs did not appear in development but showed in production (e.g. due to CE-EE merge issues).

Be sure to read general guidelines about issues and merge requests.

Working in Teams

For larger issues or issues that contain many different moving parts, you'll be likely working in a team. This team will typically consist of a backend engineer, a frontend engineer, a Product Designer and a product manager.

  1. Teams have a shared responsibility to ship the issue in the planned release.

    1. If the team suspects that they might not be able to ship something in time, the team should escalate / inform others as soon as possible. A good start is informing your manager.

    2. It's generally preferable to ship a smaller iteration of an issue, than ship something a release later.

  2. Consider starting a Slack channel for a new team, but remember to write all relevant information in the related issue(s). You don't want to have to read up on two threads, rather than only one, and Slack channels are not open to the greater GitLab community.

  3. If an issue entails frontend and backend work, consider separating the frontend and backend code into separate MRs and merge them independently under feature flags. This will ensure frontend/backend engineers can work and deliver independently.

    1. It's important to note that even though the code is merged behind a feature flag, it should still be production ready and continue to hold our definition of done.

    2. A separate MR containing the integration, documentation (if applicable) and removal of the feature flags should be completed in parallel with the backend and frontend MRs, but should only be merged when both the frontend and backend MRs are on the master branch.

Choosing Something to Work On

Start working on things with the highest priority in the current milestone. The priority of items are defined under labels in the repository, but you are able to sort by priority.

After sorting by priority, choose something that you’re able to tackle and falls under your responsibility. That means that if you’re a frontend developer, you work on something with the label frontend.

To filter very precisely, you could filter all issues for:

  • Milestone: Started

  • Assignee: Unassigned

  • Label: Your label of choice. For instance CI/CD, Discussion, Quality, frontend, or Platform

  • Sort by priority

Use this link to quickly set the above parameters. You'll still need to filter by the label for your own team.

If you’re in doubt about what to work on, ask your lead. They will be able to tell you.

Product Development Timeline

Teams (Product, UX, Engineering) continually work on issues according to their respective workflows. There is no specified process whereby a particular person should be working on a set of issues in a given time period. However, there are specific deadlines that should inform team workflows and prioritization.


Suppose we are talking about milestone m that will be shipped in month M (on the 22nd). We have the following deadlines:

  • By month M-1, 1st:

    • Release scope is finalized. In-scope issues marked with milestone m.

    • Release post (WIP merge request) created with m issues.

  • On month M-1, 8th (or next business day): Kickoff call

  • By month M, 7th: Completed m issues with docs have been merged into master. Un-started or unfinished m issues are de-scoped from m, with m being removed from them.

  • On or around M, 15th: team retrospectives should happen so they can inform the public retrospective

  • On month M, 22nd: Release shipped to production. Release post published.

    • The next Release has been tentatively planned by Product and has been shared with engineering for discussion.

  • On month M, 23rd: The patch release process for milestone m starts. This includes regular and security patch releases.

  • On month M+1, 7th: Milestone m is marked as closed. See Milestone Cleanup

    • All unfinished m issues and merge requests are automatically moved to milestone m+2, with the exception of ~security issues.

Refer to release post due dates for additional deadlines.

Note that release timelines are overlapping. For example, when a release is shipped to production on the 22nd, the scope for the following release has already been established earlier in that same month.

Engineers should create and merge in the docs as part of completing an issue by the 7th.

Refer to Feature freeze on the 7th for the release on the 22nd for further timeline details of code releases, including major/minor version releases, as well as patch releases.


At the beginning of each release, we have a kickoff meeting, publicly live-streamed to YouTube. In the call, the Product Development team (PMs, Product Designers, and Engineers) communicate with the rest of the organization which issues are in scope for the upcoming release. The call is structured by product area with each PM leading their part of the call.

The notes are available in a publicly-accessible Google doc. Refer to the doc for details on viewing the live stream.


After each release, we have a retrospective meeting, publicly live-streamed to YouTube. We discuss what went well, what went wrong, and what we can improve for the next release.

The format for the retrospective is as follows. The notes for the retrospective are kept in a publicly-accessible Google doc. In order to keep the call on time and to make sure we leave ample room to discuss how we can improve, the moderator may move the meeting forward with the timing indicated:

  1. How we improved since last month. 2 minutes. The moderator will review the improvements we identified in the last retrospective and discuss progress on those items

  2. What went well this month. 5 minutes. Teams are encouraged to celebrate the ways in which we exceeded expectations either individually or as a team.

  3. What went wrong this month. 5 minutes. Teams are encouraged to call out areas where we made mistakes or otherwise didn't meet our expectations as a team.

  4. How can we improve? 18 minutes. Teams are encouraged to discuss the lessons we learned in this release and how we can use those learnings to improve. Any action items should be captured in a GitLab issue so they can receive adequate attention before the next release.

The purpose of the retrospective is to help Engineering at GitLab learn and improve as much as possible from every monthly release. In line with our value of transparency, we live stream the meeting to YouTube and monitor chat for questions from viewers. Please check the retrospective notes for details on joining the live stream.

Live Preview

About this template


Having a well-tuned and documented development workflow not only keeps your team productive and helps you deliver software in a consistent and timely manner, but also allows you to onboard new team members much faster. It becomes especially critical when your team is maintaining a large project or working on multiple projects.

Building your software development workflow is not something that is supposed to happen within a few weeks. It takes time and it's always a cyclical process – but there is no need to reinvent the wheel.

There are many great examples of real-life development workflows that you can draw inspiration from when designing your own. This is an example of how GitLab manages their development process.

Originally published here: Engineering Workflow | GitLab.

How to manage your development workflow

There is no one-size-fits-all when it comes to workflows. You need to carefully consider your team's existing culture before implementing a new workflow. After all, the goal is to maximize productivity and effectiveness of your team without letting the process become a burden.

When evaluating potential development workflows, it may be helpful to ask yourself these questions:

Whichever development workflow you choose, it needs to be carefully documented and easily discoverable. The best place to store it is in your company wiki – which can be easily set up in Nuclino. Get started by simply importing this development workflow template into Nuclino and adapting it to your needs.

Related templates

Character illustration