The GitLab team handbook is the central repository for how we run the company. As part of our dedication to being as open and transparent as possible, the handbook is open to the world, and we welcome feedback. Please make a merge request to suggest improvements or add clarifications. Please use issues to ask questions.
We value results, transparency, sharing, freedom, efficiency, frugality, collaboration, directness, kindness, diversity, boring solutions, and quirkiness:
Results: We care about what you achieve; the code you shipped, the user you made happy, and the team member you helped. Do not compete by proclaiming how many hours you worked yesterday because we don't want someone who took the afternoon off to feel like they did something wrong. Instead, celebrate the achievements of yourself and your teammates. We want people to have the desire to ship.
Transparency: Be open about as many things as possible. By making information public we can reduce the threshold to contribution and make collaboration easier. An example is the public repository of this website that also contains this company handbook. Everything we do is public by default, for example, the GitLab CE and GitLab EE issue trackers, but also marketing and infrastructure. Transparency creates awareness for GitLab, allows us to recruit people that care about our culture, it gets us more and faster feedback from people outside the company, and makes it easier to collaborate with them. There are exceptions, material that is not public by default is documented in the general guidelines. On a personal level, you should tell it like it is instead of putting up a poker face. Don't be afraid to admit you made a mistake or were wrong. When something went wrong it is a great opportunity to say "What’s the kaizen moment here?" and find a better way without hurt feelings.
Sharing: We care about giving great software, documentation, examples, lessons, and processes to the world. An example is the MIT licensed GitLab CE. We believe that open source creates more value than it captures. We are grateful to our customers, users, partners, investors, and the open source ecosystem.
Freedom: You should have clear objectives and the freedom to work on them as you see fit. Any instructions are open to discussion. You don't have to defend how you spend your day. We trust team members to do the right thing instead of having rigid rules.
Efficiency: We care about working on the right things, not doing more than needed, and not duplicating work. This enables us to achieve more progress which makes our work more fulfilling. We do the smallest thing possible and get it out as quickly as possible. If you make suggestions that can be excluded from the first iteration turn them into a separate issue that you link. Don't write a large plan, only write the first step. Close the meta issue after you defined the first iteration. Trust that you'll know better how to proceed after something is released. You're doing it right if you're slightly embarrassed by the minimal feature set shipped in the first iteration.
Frugality: Amazon states it best with: Accomplish more with less. Constraints breed resourcefulness, self-sufficiency and invention. There are no extra points for growing headcount, budget size or fixed expense.
Collaboration: Helping others is a priority, even when it is not related to the goals that you are trying to achieve. You are expected to ask others for help and advice. Anyone can chime in on any subject, including people who don't work at GitLab. The person who has to do the work decides how to do it but you should always take the suggestions seriously and try to respond and explain.
Kindness: We don't want jerks in our team. Some companies say Evaluate People Accurately, Not "Kindly". We're all for accurate assessment but we think it must be done in a kind way. Give as much positive feedback as you can and do it in a public way. Give negative feedback in the smallest setting possible, one-on-one video calls are preferred. Clearly make negative feedback about the work itself, not the person. When giving feedback always provide at least one clear and recent example. If a person is going through a hard time in their personal life, then take that into account. An example of giving positive feedback is our thanks chat channel.
Diversity: The community consists of people from all over the world, with different backgrounds and opinions. We hire globally and encourage hiring in a diverse set of countries. We work to make everyone feel welcome and to increase the participation of underrepresented minorities and nationalities in our community and company. An example is our sponsorship of diversity events.
Boring solutions: Use the most simple and boring solution for a problem. You can always make it more complex later if that is needed. The speed of innovation for our organization and product is constrained by the total complexity we have added so far, so every little reduction in complexity helps. Don't pick an interesting technology just to make your work more fun, using code that is popular will ensure many bugs are already solved and its familiarity makes it easier for others to contribute.
Quirkiness: Unexpected and unconventional things make life more interesting. Celebrate and encourage quirky gifts, habits, behavior, and points of view. An example is our team call where we spend most of our time talking about what we did in our private lives, from fire-throwing to knitting. Open source is a great way to interact with interesting people. We try to hire people who think work is a great way to express themselves.
Working at GitLab Inc. is cooperating with the most talented people you've ever worked with, being the most productive you'll ever be, and creating software that is helping the most people you've ever reached.
We recognize that inspiration is perishable, so if you’re enthusiastic about something that generates great results in relatively little time feel free to work on that.
Do what is right for our customers and the rest of the GitLab community, do what is best over the long term, don't be evil.
We create simple software to accomplish complex collaborative tasks.
We use our own software to accomplish complex collaborative tasks.
Do not make jokes or unfriendly remarks about race, ethnic origin, skin color, gender or sexual orientation.
Use inclusive language. For example, prefer "Hi everybody" or "Hi people" to "Hi guys".
Share problems you run into, ask for help, be forthcoming with information and speak up.
Don't display surprise when people say they don't know something, as it is important that everyone feels comfortable saying "I don't know" and "I don't understand." (As inspired by Recurse.)
All our procedures and templates are stored in (mostly public) git repositories instead of Google/Word documents. This makes them easier to find and suggest changes to with the organization and shows our commitment to open collaboration outside the organization.
Work out in the open, try to use public issue trackers and repositories when possible.
Most things are public unless there is a reason not to; not public by default are: financial information, legal, job applications/compensation/feedback and partnerships with other companies.
Share solutions you find and answers you receive with the whole community.
If you make a mistake, don't worry, correct it and proactively let the affected party, your team, and the CEO know what happened, how you corrected it and how, if needed, you changed the process to prevent future mistakes.
You can always refuse to deal with people who treat you badly and get out of situations that make you feel uncomfortable.
Everyone can remind anyone in the company about these guidelines. If there is a disagreement about the interpretations, the discussion can be escalated to more people within the company without repercussions.
If you are unhappy with anything (your duties, your colleague, your boss, your salary, your location, your computer) please let your boss, or the CEO, know as soon as you realize it. We want to solve problems while they are small.
We want to have a great company so if you meet people that are better than yourself try to recruit them to join the company.
Make a conscious effort to recognize the constraints of others within the team. For example, sales is hard because you are dependent on another organization, and Development is hard because you have to preserve the ability to quickly improve the product in the future.
For each action or comment, it helps to ask yourself (i) does this help the company achieve its strategic goals? (ii) is this in the company's interest, and finally, (iii) how can I contribute to this effort/issue in a constructive way?
There is no need for consensus, make sure that you give people that might have good insights a chance to respond (by /cc'ing them) but make a call yourself because consensus doesn't scale.
Everyone at the company cares about your output. Being away from the keyboard during the workday, doing private browsing or making personal phone calls is fine and encouraged.
If you fix something for GitLab.com or one of our users, make sure to make that the default (preferred) and radiate the information in the docs. We should run GitLab.com with the same default settings and setup our users would also have.
Everything is always in draft and subject to change, including this handbook. So do not delay documenting things and do not include "draft" in the titles of documents. Ensure everyone can read the current state. Nothing will ever be finished.
Explicitly note what next action you propose or expect and from whom.
Before replying to a request, complete the requested task first. Otherwise, indicate when you plan to complete it in your response. In the latter case, always send a message after the task is subsequently completed.
Respect the privacy of our users and your fellow team members. Secure our production data at all times. Only work with production data when this is needed to perform your job. Looking into production data for malicious reasons (for example, LOVEINT or spying on direct messages of team members) is a fireable offense.
Most guidelines in this handbook are meant to help, and unless stated otherwise, are meant to help more than being absolute rules. Don't be afraid to do something because you can't oversee all guidelines. Be gentle when reminding people about these guidelines, saying for example, "It is not a problem, but next time please consider the following guideline from the handbook."
At GitLab our handbook is extensive and keeping it relevant is an important part of everyone's job. The reasons for having a handbook are:
Reading is much faster than listening.
Reading is async, you don't have to interrupt someone or wait for them to become available.
Recruiting is easier if people can see what we stand for and how we operate.
Retention is better if people know what they are getting into before they join.
Onboarding is easier if you can find all relevant information spelled out.
Teamwork is easier if you can read how other parts of the company work.
Discussing changes is easier if you can read what the current process is.
Communicating change is easier if you can just point to a diff.
Everyone can contribute to it by proposing a change via a merge request.
Documenting things in the handbook takes more time initially and it requires thinking. But it saves time over a longer period and it is essential to scale and adapt our organization. It is not unlike writing tests for your software. Please follow these guidelines and remind others of them.
If you need to discuss with a team member for help please realize that probably the majority of the community also doesn't know, be sure to document the answer to radiate this information to the whole community. After the question is answered, discuss where it should be documented and who will do it. You can remind other people of this by asking "Who will document this?"
When you discuss something in chat always try to link to a URL where relevant, for example, the documentation you have a question about or the page that answered your question. You can remind other people of this by asking "Can you please link?"
To change a guideline or process, suggest an edit in the form of a merge request. After it is merged you can talk about it during the team call if applicable. You can remind other people of this by asking "Can you please send a merge request for the handbook?"
Communicate process changes by linking to the diff (a commit that shows the changes before and after). Do not change the process first, and then view the documentation as a lower priority task. Planning to do the documentation later inevitably leads to duplicate work communicating the change and to outdated documentation. You can remind other people of this by asking "Can you please update the handbook first?"
When communicating something always include a link to the relevant (and up to date) part of the handbook instead of including the text in the email/chat/etc. You can remind other people of this by asking "Can you please link to the relevant part of the handbook?"
If you copy content please remove it at the origin place and replace it with a link to the new content. Duplicate content leads to updating it in the wrong place, keep it DRY.
We're a distributed, remote-only company where people work remotely without missing out. For this, we use asynchronous communication and are as open as we can be by communicating through public issues, chat channels, and placing an emphasis on ensuring that conclusions of offline conversations are written down. These communication guidelines are meant to facilitate smooth communication in an ever-growing remote-only company. Please keep in mind that you represent GitLab and our culture, also on Social Media. When commenting on posts please keep in mind: "Don't argue but represent."
All written communication happens in English, even when sent one on one, because sometimes you need to forward an email or chat.
It is very OK to ask as many questions as you have, but ask them so many people can answer them and many people see the answer (so use issues or public chat channels instead of private messages or one-on-one emails) and make sure you try to document the answers.
If you mention something (a merge request, issue, commit, webpage, comment, etc.) please include a link to it.
All company data should be shareable by default. Don't use a local text file but leave comments on an issue.
When using email, send one email per subject as multiple items in one email will cause delays (have to respond to everything) or misses (forgot one of the items).
Always reply to emails, even when no action is needed. This lets the other person know that you received it. A thread is done when there is a single word reply, such as OK, thanks, or done.
If you forward an email without other comments please add FYI (for your information) or FYA (for your action). If you forward an external request with FYA it doesn't mean that the company should do whatever is proposed, it just means the person who forwarded it will not follow up on the request themselves and expects you to do so instead.
Email forwarding rules are specified in the shared GitLab Email Forwarding Google Doc accessible only to people in the company. If you want to be added or removed from an internal alias (for example, "email@example.com"), change a rule, or add a forwarding email alias, please suggest an edit in the doc.
Emails are asynchronous, for example, if your manager emails you on a weekend it is fine to reply during the workweek.
If an email is or has become urgent feel free to ping people via chat referencing the subject of the email.
If you use chat please use a public channel whenever possible, mention the person you want to reach if it is urgent. This ensures it is easy for other people to chime in, and easy to involve other people, if needed.
In chat try to keep the use of keywords that mention the whole channel to a minimum. They should only be used for pings that are both urgent as well as important. By overusing channel mentions you make it harder to respond to personal mentions in a timely manner since people get pinged too frequently.
If you agree in a chat to start a video call (typically by asking "Call?") the person that didn't leave the last comment starts the call. So either respond to the "Call?" request with a video link or say "Yes" and let the other person start it. Don't say "Yes" and start a call 5 seconds later since it is likely you'll both be creating a video call link at the same time.
Work on website edits via commits to a merge request. Never use a Google Doc for something non-confidential that is intended for the website.
If you do need a Google Doc, create one with your company G Suite (formerly Google Apps) account. By default, share it with the whole company using the Anyone at GitLab can find and access link sharing permission and the Anyone within GitLab can edit access permission (preferred) or the Anyone within GitLab can comment access permission. Easily do this by creating Google Docs within a Shared Folder in Google Drive.
When referring to a Google Doc in the handbook, refrain from directly linking it. Instead, indicate the name of the doc. (In the past, linking a Google Doc has led to inadvertently opening the sharing settings beyond what was intended.) This also helps prevent spam from people outside GitLab requesting accessing to a doc when clicking its link.
If you are having trouble finding a shared Google Doc, make sure you Search <your domain> in Google Drive.
In our handbook, if you find yourself wondering whether it is better to provide a public link to a Google Doc vs. writing out the content on the website, use the following guideline: Is this document frequently adapted / customized? If yes, then provide a link, making sure that the document can be commented on by anyone with the link. For instance, this is how we share our employment contracts. If the document is rarely customized, then provide the content directly on the site and deprecate the Google Doc.
Use video calls if you find yourself going back and forth in an issue/via email or over chat.
Having pets, children, significant others, friends and family visible during video chats is encouraged. If they are human, ask them to wave at your remote team member to say "Hi".
Thank people that did a great job in our "Thanks" chat channel. If someone is a team member just @ mention them. If multiple people were working on something try mentioning each person by "@name". "Thanks everyone" does not say much.
To thank someone who is not a team member, mention your manager, our People Ops Coordinator, the name of the person, a quirky gift and link to their work. For example, "@manager, @peopleopscoordinator: Joe deserves a lawnmower for link". With your manager's blessing, the People Ops Coordinator will approach the person in question for their address saying we want to send some swag. We'll ship it in gift wrap with "Thanks for your great work on link, love from @gitlab".
Don't thank the CEO or other executives for something that the company paid for, thank GitLab instead.
Not sure where to go?
If there is something that you want to discuss, but you do not feel that it is a reasonable option to discuss with either your manager or CEO, then you can reach out to any of the other C-level team members or our board member Bruce Armstrong.
Always create an issue for things you work on. If it is worth spending time on, it is worth creating an issue for it since that enables other people to learn and help. You can always edit the description or close it when the problem is something different or disappears.
Double link issues to prevent internal confusion and us failing to report back to the reporters. For example, open an issue with a link to ZenDesk and close the issue with a copy of the response. Or add "Report: " lines to the description with links to relevant issues and feature requests and ensure they are closed and note this with a comment. If you are not responsible for reporting back please do not close an issue, instead re-assign it.
If two issues are related, crosslink them (a link from each issue to the other one). Put the link at the top of each issue's description with a short mention of the relationship (Report, etc.). If there are more than 2 issues, use one issue as the central one and crosslink all issues to this one. Please, also crosslink between ZenDesk and GitLab issues.
After a discussion about a feature update the issue body with the consensus or final conclusions. This makes it much easier to see the current state of an issue for everyone involved in the implementation and prevents confusion and discussion later on.
Give the community the chance to help. For example, place issues on the feedback tracker, leave comments in rake check tests about what you can run manually and ask "Can you send a merge request to fix this?"
Submit the smallest item of work that makes sense. When creating an issue describe the smallest fix possible, put suggestions for enhancements in separate issues and link them. If you're new to GitLab and are writing documentation or instructions, submit your first merge request for at most 20 lines.
Do not leave issues open for a long time, issues should be actionable and realistic. If you are assigned to an issue but don't have time to work on it, assign it to someone else. If nobody is assigned to an issue and it is not a priority, please ensure the community can help and close it.
Make a conscious effort to prioritize your work. The priority of items depends on multiple factors: Is there a team member waiting for the answer? What is the impact if you delay it? How many people does it affect, etc.? This is detailed in Engineering Workflow.
Use the public issue trackers on GitLab.com for everything since we work out in the open. We do still use some private issue trackers on our internal dev.gitlab.org server, such as for organizational issues that do not have a home in one of the public team trackers that can be found on the team structure page.
We try not to assign issues to people but to have people pick issues in a milestone themselves.
Assign an issue to yourself as soon as you start to work on it, but not before that time. If you complete part of an issue and need someone else to take the next step, re-assign the issue to that person.
When re-assigning an issue, make sure that the issue body contains the latest information. The issue body should be the single source of truth.
When working on an issue, ask for feedback from your peers. For example, if you're a designer and you propose a design, ping a fellow designer to review your work. If they approve, you can move it to the next step. If they suggest changes, you get the opportunity to improve your design. This promotes collaboration and advances everyone's skills.
We keep our promises and do not make external promises without internal agreement.
Even when something is not done, share it internally so people can comment early and prevent rework. Mark the merge request Work In Progress so it is not merged by accident.
When you create a merge request, mention the issue(s) that it solves in the description. If any followup actions are required on the issue after the merge request is merged, like reporting back to any customers or writing documentation, avoid auto closing it by saying Fixes #1 or Closes #1.
Once a merge request is created, make sure to assign it to the proper person:
For example a merge request that fixes a frontend issue should have the Frontend label and be assigned to a Frontend Engineer for review. For other workflow labels please see PROCESS.md.
A merge request that is related to Continuous Integration should be assigned to the GitLab CI lead.
If a merge request fixes a UX issue, it should be assigned to a UX Designer for review.
All other merge requests should be assigned for review to either a merge request miniboss or endboss. You can find the people with these roles on the team page.
Once a merge request has gone through review by a miniboss, they will assign it to an endboss who will do a final review and perform the actual merge if satisfied.
When you are done with your merge request, remove the WIP prefix and assign the merge request to someone to review and merge it. You can still make changes based on feedback of course, but by removing the WIP prefix it clarifies that the main body of work has been completed.
If a discussion has been addressed, select the "Resolve discussion" button beneath it to mark it resolved. If someone disagrees, they can click "Unresolve discussion" and explain what is still missing.
When a merge request is done, set its milestone to the version it should be included in.
If you are assigned to review and merge a merge request and would like the creator to make some changes, comment on the merge request and assign it back to the creator. When they have addressed the concern, they will re-assign it to the reviewer.
If you are assigned to merge a merge request and there is a merge conflict, consider trying to resolve it yourself instead of asking the merge request creator to resolve the conflict. If it is easy to resolve you avoid a round trip between you and the creator, and the merge request gets merged sooner. This is a suggestion, not an obligation.
If you ask a question to a specific person, always start the comment by mentioning them; this will ensure they see it if their notification level is mentioned and other people will understand they don't have to respond.
Do not close an issue until it is fully done, which means code has been merged, it has been reported back to any customers and the community, all issue trackers are updated and any documentation is written and merged.
When closing an issue leave a comment explaining why you are closing the issue.
If a user suggests an enhancement, try and find an existing issue that addresses their concern, or create a new one. Ask if they'd like to elaborate on their idea in one of these issues.
It you notice that the tests for the master branch of GitLab CE are failing (red) or broken (green as a false positive), fixing this takes priority over everything else development related, since everything we do while test are broken may break existing functionality, or introduce new bugs and security issues. If the problem cannot be fixed by you within a few hours, because if it is too much work for one person and/or you have other priorities, create an issue, post about it in #development, and @mention the Backend Leads and CTO in the issue and on Slack, so that they are aware of it, the problem can be properly investigated, and the resources can be assigned to fix it as quickly as possible.
It you find or are alerted of a security issue, major or small, fixing this takes priority over everything else development related. Create an issue, post about it in #development, and @mention the Backend Leads and VP of Engineering in the issue and on Slack, so that they are aware of it. If the problem cannot be fixed by you within a few hours, because if it is too much work for one person and/or you have other priorities, communicate this to them, so that the problem can be properly investigated, and the resources can be assigned to fix it as quickly as possible.
The team call is every workday except Friday from 8:30am to 9:00am Pacific Time (mostly 5:30pm - 6:00pm Central European Time). Everyone at GitLab is invited to this call.
We also have a team call for team members in the APAC region on Mondays from 6:30pm to 7:00pm Pacific Time (mostly 8:00am Tuesday in APAC), to share their weekend update. This call will also be recorded so the rest of the team can see what their colleagues have been up to! Everyone is encouraged to join this call as well, but it is not mandatory.
Every last Friday of the month we have an AMA to talk about anything our team is thinking about.
We use Zoom for the call since Google Hangouts is capped at 15 people. The link is in the calendar invite and also listed at the top of the team agenda Google Doc called Team Agenda.
The call is recorded automatically, and we have a 1 GB limit for recordings which is roughly sufficient for 3 days; after this is full, the recording will not be stored. Access recordings in Zoom using the generic credentials in the Shared vault in 1Password; find "My Recordings". Remember to actively log out after viewing or downloading the recording, otherwise you will appear as the Moderator on subsequent calls.
We start on time and will not wait for people.
The person who has the first item on the agenda starts the call.
If you are unable to attend just add your name to the team agenda as "Not attending".
We start by discussing the subjects that are on the agenda for today.
Everyone is free to add subjects. Please start with your name and be sure to link to an issue, merge request or commit if it is relevant.
When done with a point mention the subject of the next item and hand over to the next person.
When someone passes the call to you, no need to say, “Can you hear me?” Just begin talking. If we can’t hear you, we’ll let you know.
We have functional group updates (1 group per call) for the following groups: Marketing, Sid, Product, Sales, Ops, Support, People Ops, Finance, Development, Front-end, and UX/UI. Please limit the updates to 10 minutes or less.
We also encourage team members who are not the head of the department to give the functional group update. This will support professional development as well as give the organization a different view of what that department is working on.
We ask 15-20 people per day to share updates about the most exciting thing from your past or upcoming week/weekend. If anyone has something they'd like to talk about, last person in the list will ask the group if they have anything else to share.
The team agenda lists who is meant to speak on which day; this can be altered daily if conflicts arise.
There is no need to excuse yourself with "I didn't do anything interesting", "I just watched television" or "That's all". It is not a competition. Instead share the most interesting detail, for example what television show you watched, book you are reading, video game you played or what recipe you cooked.
The sequence of asking people is in order of joining the company, as shown on the team page. If there are non-team page people in the call we end with those.
It is OK to talk over people or interrupt people to ask questions, cheer for them or show your compassion. This to encourage more conversation and feedback in the call.
Please look if the person you hand over to is present in the participant list so you don't hand over to someone who is not present.
The last person wishes everyone a good day.
Even if you cannot join the call, consider reviewing the recorded call or at minimum read through the team agenda and the links from there. We often use the team call to make announcements or discuss changes in processes, so make sure to catch up on the news if you have missed a team call (or more).
Random Chat and Room
The #random chat channel is your go-to place to share random ideas, pictures, articles, and more. It's a great channel to check out when you need a mental break.
Come hang out any time in the random room, an open Google Hangout video chat where anyone with a GitLab email address can come and leave as they please. The link is in the description of the #random chat channel; consider bookmarking it. This room is open for all and should be distinct from the Coffee Break Calls, which are 1x1 conversations between teammates.
If you want to ask team members if they are available for an event please send a new calendar appointment from and to the company address. This makes it easier for people to check availability and to put on their calendar. It automatically shows up on calendars even when the email is not opened. It is easier to signal presence and to see the status of everyone. Please respond quickly to invites so people can make plans.
If there are materials relevant for a calendar meeting please add the URL to the meeting invite description. Normally this would be a Google Doc for the agenda and any relevant issues.
Every scheduled meeting should have an agenda, including any preparation materials. Put the agenda in a Google Doc that has edits rights for all participants (including people not part of GitLab Inc.). Take notes of the points and todo's during the meeting. Nobody wants to write up a meeting after the fact and this helps to structure the thought process and everyone can contribute. Being able to structure conclusions and follow up actions in realtime makes a video call more effective than an in-person meeting.
If you want to check if a team member is available for an outside meeting, create a calendar appointment and invite the team member only, after they respond yes then invite outside people.
When scheduling a call with multiple people, invite them using a Google Calendar that is your own, or one specific to the people joining, so the calendar item doesn't unnecessarily appear on other people's calendars.
If you want to move a meeting just move the calendar appointment instead of reaching out via other channels, note the change at the top of the description.
If you want to schedule a meeting with a person not on the team please use Calendly.
When scheduling a meeting we value people's time and prefer the "speedy meetings" setting in our Google Calendar. This gives us meetings of, for example, 25 or 50 minutes leaving some time to write notes etc before continuing to our next call or meeting. (This setting can be found under the calendar Settings menu at "default event duration")
When creating a calendar event that will be used company wide, please place it on the GitLab Availability Calendar. That way the event is easily located by all individuals.
For smaller meetings we use Google Hangouts or Appear.in, for larger meetings we prefer Zoom (Google Hangouts technical limit is 15 for scheduled meetings).
For meetings that are scheduled via calendar there is automatically a Google Hangout URL added, this is the meeting place. Having a url in advance is much more reliable than trying to call via hangouts as the meeting start.
Use a headset with a microphone, Apple Earpods are great. Do not use computer speakers, they cause an echo. Do not use your computer microphone, it accentuates background noise. If you want to use your Bose headphones that is fine but please ensure the microphone is active.
Consider using a utility to easily mute/unmute yourself, see Shush in the tools section.
In video calls everyone should own camera and headset, even when they are in the same room. This helps to see the person that is talking clearly on the camera and their name in the list. It also allows people to easily talk and mute themselves. And using a headset prevents an echoing. You wouldn't share an office seat together, don't share your virtual seat at the table.
User Communication Guidelines
Keep conversations positive, friendly, real, and productive while adding value.
If you make a mistake, admit it. Be upfront and be quick with your correction. If you're posting to a blog, you may choose to modify an earlier post, just make it clear that you have done so.
There can be a fine line between healthy debate and incendiary reaction. Try to frame what you write to invite differing points of view without inflaming others. You don’t need to respond to every criticism or barb. Be careful and considerate.
Answer questions, thank people even if it’s just a few words. Make it a two way conversation.
When facing negative comment, respond patiently and treat every user as an individual, people with the strongest opinions can turn into the strongest supporters.
Writing Style Guidelines
At GitLab, we use American English as the standard written language.
Do not use rich text, it makes it hard to copy/paste. Use Markdown instead.
We use Unix style (lf) line endings, not Windows style (crlf), please ensure *.md text eol=lf is set in the repository's .gitattributes and run git config --global core.autocrlf input on your client.
Do not create links like "here" or "click here". All links should have relevant anchor text that describes what they link to, such as: "GitLab CI source installation documentation".
Always use ISO dates in all writing and legal documents, yyyy-mm-dd, e.g., 2015-04-13, and never 04-13-2015 or 13-04-2015
If you have multiple points in a comment or email, please number them to make replies easier.
When you reference an issue, merge request, comment, commit, page, doc, etc. and you have the URL available please paste that in.
In URLs, always prefer hyphens to underscores.
The community include users, contributors, core team members, customers, people working for GitLab Inc., and friends of GitLab. If you want to refer to 'people not working for GitLab Inc.' just say that and don't use the word community. If you want to refer to people working for GitLab Inc. you can also use 'the GitLab Inc. team' but don't use the 'GitLab Inc. employees'.
All people working for GitLab the company are the GitLab team, we also have the Core team that is part GitLab team, part volunteers.
Please always refer to GitLab Inc. people as team members, not employees.
Use inclusive and gender-neutral language in all writing. So for example, write "they, their" instead "he, his".
Always write GitLab with a capitalized G and L, even when writing GitLab.com.
Do not use acronyms when you can avoid it as you can't assume people know what you are talking about. Example: instead of MR, write merge request.
Beamy is our company conference call robot. It lives in the San Francisco Howard St. office. Its main purpose is to allow those outside of the office a view into the space and people. When you call in to the beam your face will appear on the screen (so make sure your webcam works) and you can drive the robot around the office. It simulates being in the space without physically being there. It is really cool and everyone should try it and have fun with it.
You need an invite email to connect and to download a desktop client, please @mention Emily in the #general channel if you don't have the invite yet.
Beamy times: 8am until 6pm Pacific time on workdays and during all company events, for other times please @mention Sytse in the #valley channel to see if it is OK. It is on auto connect so you'll beam right in.
Once you are sent an invite you can beam in at any time and drive around our beam. Don’t forget to park it back on the charger when you are done. You can do so by driving up to the charger, when you see a green outline press AND HOLD 'p' until it's parked. Make sure it is charging, otherwise try again.
If you don't use headphones be careful about your volume and microphone placement, it might start singing, if so immediately mute your microphone and switch to headphones.
More info can be found at https://www.suitabletech.com/
Please report any questions or issues you have about the beam by @mentioning Emily in the #general channel.
Company phone number
If you need to provide the details of GitLab's contact information you can take the address of the office for reference; or the mailing address of the office in the Netherlands if that is more applicable.
If a phone number is required, leave this field empty by default. If that is not possible, then use the general number (+1-415-761-1791), but be aware that this number simply guides to a voice message that refers the caller back to contacting us via email.
On-Call Rotation and Scheduling
We have on-call heroes (see the team page) to respond quickly to GitLab.com downtime, and customer emergencies. Details about the schedule and how to swap duty in the On-Call page.
Take proper care of any confidential information you get from our customers.
If you copy code always check the license and attribute when needed or appropriate.
Check community contributions and do not merge it when there can be doubt about the ownership.
Only the CEO of the company signs legal documents such as NDAs. Sales people and the business office manager can upload them via HelloSign.
View our DMCA policy in regards to copyright / intellectual property violations
In keeping with our values of results, freedom, efficiency, frugality, and boring solutions, we expect team members to take responsibility to determine what they need to purchase or expense in order to do their jobs effectively. We don't want you to have to wait with getting the items that you need to get your job done. You most likely know better than anyone else what the items are that you need to be successful in your job. The guidelines below describe what people in our team commonly expense.
Spend company money like it is your own money.
You don't have to ask permission before making purchases in the interest of the company. When in doubt, do inform your manager before the purchase, or as soon as possible after the purchase.
It is uncommon for you to need all of the items listed below, use your best judgement and buy them as you need them. If you wonder if something is common, feel free to ask People Ops (and in turn, People Ops should update the list).
It is generally easiest and fastest for you to make the purchases yourself, but feel free to reach out to People Ops if you would like help in acquiring some items. Just include a link and your shipping address in an email, and People Ops will be happy to place the order.
Employees: file your expense report no later than 7 days after the end of the calendar quarter that you made the purchase in. Contractors: include receipts with your invoices.
Any non-company expenses paid with a company credit card will have to be reported to your manager as soon as possible and refunded in full within 14 days.
Items. The company will pay for the following items if you need it for work or use it mainly for business, and local law allows us to pay for it without incurring payroll taxes. Items paid for by the company are property of the company and need to be reported with serial numbers etc. to People Ops for proper asset tracking. Since these items are company property, you do not need to buy insurance for them unless it is company policy to do so (for example, at the moment we do not purchase Apple Care), but you do need to report any loss or damage to PeopleOps as soon as it occurs. Links in the list below are to sample items, other options can be considered:
Notebook: we recommend getting a MacBook Pro 13-inch retina with 512GB of storage and 16GB of memory for engineers and a Macbook 256GB for non-engineers (Mention to the Apple Store that you are buying it for GitLab so that we can qualify for business discounts). Running Unix makes it easier to work with git from the command line so we strongly recommend against Windows laptops. WebEx screen sharing does not work from a Linux platform while it is one of the more common conferencing tools used with customers that we all need to interact with from time to time. Additionally 1password doesn't have a native client for Linux and the web interface in Firefox is not that good. If you have strong reasons to want to deviate from this guideline just ask your manager.
Internet connection subscription. (For employees in the Netherlands, see the Regeling Internet Thuis and send the signed form to People Ops once completed).
Mobile subscription, we commonly pay for that if you call a lot as a salesperson or executive.
Telephone land line (uncommon, except for positions that require a lot of phone calls)
Skype calling credit, we can autofill your account (uncommon, since we mostly use Google Hangouts, Appear.in, Zoom, and WebEx)
Google Hangouts calling credit
Office space (if working from home is not practical)
Work-related online courses
The company will pay for all courses related to learning how to code, and you may also allocate work time to take courses that interest you. If you are new to development, we encourage you to learn Git through GitLab, and feel free to ask any questions in the #git-help Slack channel.
Work-related conferences, including travel, lodging and meals. If total costs exceed $500, reimbursement requires prior approval from your manager.
Travel to visit team members, including flights, trains, and transportation to/from the airport. Reimbursement requires prior approval from your manager. Lodging, meals and local travel while visiting may not be covered out of fairness to the people being visited.
It may be acceptable to cover some meals, where there are either a large number of team members present or the purpose is work-related.
Your manager and the VP of your department will be able to provide guidance on specific cases.
Business travel upgrades per round-trip (i.e. not per each leg of the flight):
Up to the first EUR 300 for an upgrade to Business Class on flights longer than 8 hours.
Upgrade to Economy Plus if you’re taller than 1.95m / 6’5” for flights longer than 2 hours.
Up to the first EUR 100 for an upgrade to Economy Plus (no height restriction) on flights longer than 8 hours.
Something else? No problem, and consider adding it to this list if others can benefit as well.
If you are a contractor, please submit an invoice with receipts attached to firstname.lastname@example.org.
If you are an employee, GitLab uses Expensify to facilitate the reimbursement of your expenses. As part of onboarding you will receive an invitation by email to join GitLab's account. Please set up your account by following the instructions in the invitation.
If you are new to Expensify and would like a brief review, please see Getting Started
For step by step instructions on creating, submitting and closing a report please see Create, Submit, Close
If you are an employee with a company credit card, your company credit card charges will automatically be fed to a new Expensify report each month. Please attach receipts for these expenses (per the Expense Policy, see below) within 5 business days after the end of the month. These amounts will not be reimbursed to you but Expensify provides a platform for documenting your charges correctly.
Max Expense Amount - 5,000 USD or 5,000 EUR
Receipt Required Amount - 25 USD or 25 EUR
Paid Time Off
Don't frown on people taking time off, but rather encourage that people take care of themselves and others.
Working hours are flexible, you are invited to the team call if you are available, and if you want you can post to the #working-on chat channel what is on your mind so others can offer suggestions.
You don't need to worry about taking time off to go to the gym, take a nap, go grocery shopping, doing household chores, helping someone, taking care of a loved one, etc. If something comes up or takes longer than expected and you have urgent tasks and you're able to communicate, just ensure the rest of the team knows and someone can pick up any urgent tasks.
Encourage your co-workers to take time out when you become aware that they are working long hours over a sustained period.
We have an "unlimited" time off policy. This means that:
You do not need to ask permission to take time off unless you want to take more than 25 consecutive calendar days.
Always make sure that your job responsibilities are covered while you are away.
We strongly recommended to take at least a minimum of 2 weeks of vacation per year, if you take less your manager might follow up to discuss your work load.
You do need to ensure that not more than half of the people that can help with availability emergencies (the on-call heroes), regular support, sales, or development are gone at any moment. You can check for this on the availability calendar, so be sure to add appointments early.
Please see the On-Call page for information on how to handle scheduled leave for someone from the on-call team.
Add an appointment to the GitLab availability calendar as you know your plans, you can always change it later.
In case it can be useful add your planned time off as a FYI on the next agenda of the team call.
We will help clients during official days off, unless they are official days off in both the Netherlands and the U.S. We try to have people working who are in a country that don't have an official day off. If you need to work during an official day off in your country, you should take a day off in return.
If you have to respond to an incident while being on-call outside of your regular working hours, you should feel free to take off some time the following day to recover and be well-rested. If you feel pressure to not take the time off to rest, refer to this part of the handbook and explain that you had to handle an incident.
The following incentives are available for GitLab team members. Also see our separate page on benefits available to GitLab team members.
Sales Target Dinner Evangelism Reward
Since reaching sales targets is a team effort that integrates everything from making a great product to providing top notch customer support and everything in between, we reward all team members (not just the Sales team) for every month that we reach our Sales Targets. The incentive is 100 USD to each team member for the purpose of evangelizing the GitLab story. You may use the incentive at a restaurant of your choice. Enjoy!
The CEO, or CRO will announce on the team call if the target was met.
To claim the incentive, please submit your receipt through Expensify or include on your contractor invoice as a reimbursable expense.
Indicate on your receipt and in the comment section in expensify "GitLab evangelism" and the names of the other participants.
You should spend the incentive on eating out, and can be reimbursed up to the maximum of 100 USD.
Use the incentive in the month following the announcement. So for example, if we reach our target in March, use your incentive in April.
If you cannot, or decide not to, use the incentive in the expected month, you can carry it over to the next month by notifying Accounts Payable before the 22nd of the month (release day!). You can only carry over one month in this way.
Every now and then, individual team members really shine as they go above and beyond their regular responsibilities and tasks.
We recognize this through the #thanks channel, and sometimes also through a discretionary bonus.
Managers can recommend their team members to the CEO for a $1,000 bonus.
On team call, the manager announces the “who” and “why” of the bonus; and the "why" should be tied to our values.
The manager should send a brief email that explains the bonus (same as the team call blurb) and states the amount to People Ops and our Controller who will process the information into payroll and BambooHR. People Ops should confirm when these steps have been taken, back to the manager.
If you think you are meeting the requirements for another title, want to change jobs within the company, or think your growth should be reflected in your compensation please feel free to discuss with your manager.
Chances are that if you work at GitLab, you have great friends and peers who would also be fantastic additions to our Team and who may be interested in one of the current Job Openings. To help us grow the team with exceptional people, we have referral bonuses that work as follows:
If you refer a great candidate and they are hired, then you receive a $1,000 bonus once the new team member has been with the company for 3 months.
If the new team member receives a discretionary bonus within the first 6 months of their hire, then you also get a $1,000 bonus.
Exceptions: no bonuses for hiring people who report to you, and no bonus for the executive team.
When your referral applies for an opening, make sure that they enter your name on the application form.
GitLab is a remote-first company with team members all over the world (see the map on our Team page ). If you want to visit a colleague in another part of the world, or promote GitLab at events in another country, then present your travel plan to your manager or the CEO, and you can receive up to $2,000 in support for your plan!
As an example, the first grant was handed to a team member who will be traveling to 6 team members in different countries during 6 months, and this team member will receive the maximum grant of $2,000.
To claim the approved award, include a line item on your expense report or invoice with the approval email as the receipt. The entire award can be claimed from the first month of travel to up to 3 months after the travel is completed.
Signing Legal Documents
Only C-level executives can sign legal documents, with the exception of NDAs covering a physical visit of another organization. When working with legal agreements with vendors, consultants, and so forth, bear in mind the signature authorization matrix. If you need to sign, fill out, send or retrieve documents electronically, please send a description of what you need or a copy of the document to email@example.com with the following information:
Names and email addresses of those who need to sign the document.
Any contractual information that needs to be included in the document.
Deadline (or preferred timeline) by which you need the document prepared (i.e. staged in HelloSign for relevant signatures)
Names and email addresses of those who need to be cc-ed on the signed document.
The process that "legal" (currently a combination of People Ops and Finance) will follow is:
Prepare the document as requested.
Have the requestor check the prepared document, AND obtain approval from the CFO or CEO (such approval may be explicit in the email thread that was sent to legal@, in which case a second approval is not needed unless there have been significant edits to the document).
Stage the document for signing in HelloSign and cc (at minimum) the requestor and legal@.
Once signed, the person who staged it in HelloSign places the document in the contracts folder on Google Drive.
Working remotely has a lot of advantages, but also a couple of challenges. The goal of this section is to provide information and tips to maximize the advantages and make you aware of the challenges and provide tips on how to deal with them.
Probably the biggest advantage of working remotely and asynchronously is the flexibility it provides. This makes it easy to combine work with your personal life although it might be difficult to find the right balance. This can be mitigated by either explicitly planning your time off or plan when you do work. When you don't work it is recommended to make yourself unavailable by turning off Slack and closing down your email client. Coworkers should allow this to work by abiding by the communication guidelines.
If you worked at an office before, now you lack a default group to go out to lunch with. To look at it from a different perspective, now you can select who you lunch with and who you do not lunch with. Haven't spoken to a good friend in a while? Now you can have lunch together.
Coffee Break Calls
Understanding that working remotely leads to mostly work-related conversations with fellow GitLabbers, everyone is encouraged to dedicate a few hours a week to having social calls with any GitLab employee - get to know who you work with, talk about everyday things and share a virtual cuppa' coffee. We want you to make friends and build relationships with the people you work with to create a more comfortable, well-rounded environment. The Coffee Break calls are different to the Random Room video chat, they are meant for give you the option to have 1x1 calls with specific teammates you wish to speak with and is not a random, open-for-all channel but a conversation between two teammates.
Tools and Tips
A lot of tools we use are described in the rest of the handbook (GitLab, Google Docs, Google Hangouts, 1Password, etc.). This section is for tools that don't fit anywhere else.
Calendly connects to your Google calendar so people can book a time with you without having a Google Account.
Link it to your GitLab Google Calendar to make it possible for people to schedule a call with you
All meetings will have the same Google Hangout URL on your calendar based on your @gitlab.com email handle. You can use that in the booking text above. Events on your calendar will automatically have the Google Hangout URL added, so you can use the plus landing page to quickly jump into the call. Please note that the appointment will show up in other peoples calendar with a different link, to it is essential that you set a text with the link for your time slot as specified below.
Set up the 45 minute time slot with the following event description text (replacing XXXXX with your @gitlab.com handle):
This will be a Google Hangout at https://plus.google.com/hangouts/_/gitlab.com/XXXXX
If you intend to use any of the other event types, make sure to add this to their event descriptions as well.
For people outside of GitLab Inc, send them your Calendly link that links directly to the 45 minute time slot: "Are any of the times on https://calendly.com/XXXXX/45min/ convenient for you? If so please book one, if not please let me know what times are good for you and we'll find an alternative."
Add your Calendly link to your Slack profile. For Display Text, use this line: Schedule a meeting with me! so team members can schedule a 1:1 call with you in GitLab, by simply clicking your Calendly link in your Slack profile.
Keep in mind that unlike normal Google Calendar events, Calendly events are not automatically synchronized between both parties when changes are made. If an event needs to be cancelled or modified, make sure to use Calendly to do so.
$4.99 tool for OSX that allows you to use you fn key as a push to talk or push to mute. Never again will you have switch window focus to Google Hangout or Zoom to speak or mute. The icon will show the current state of your mic input (x means muted). With a right click you can switch from push to talk to push to mute. Don't forget to unblock your mic in Zoom/Google Hangouts immediately after joining. Be warned that page up with fn+down arrow will activate it. Use space for page down instead of fn+up arrow.
Disabling OS X Notification Center
During a presentation or screen share, you might want to disable your notifications on OS X to prevent distractions or possible embarrassment.
The Notification Center can be quickly disabled by Option-Clicking the menu bar icon in the top right of your screen. This disables notifications until the next day. Option-Click again to re-enable immediately. Alternatively, click on the Notification Center icon, then scroll up to reveal the "Do Not Disturb" toggle.
To set up a Zoom meeting, sign up for a free Basic account, and share the link for your "personal meeting room" with your participants. Note that on the Basic license, meetings are capped at 50 people, and meeting durations are capped at 40 minutes. If you need to be able to organize calls longer than 40 minutes using Zoom, contact People Ops to be granted a Pro account. By default, only Service Engineers and members of the Sales team are given Pro accounts during onboarding since their job routinely involves making video calls with (potential) customers.
To record the meeting, simply click on record, which will save an .mp4, .mp3, and .txt files for chat, to your local hard drive.
Please add instructions on how to add the resulting video to our YouTube channel.
It might be useful to add a Gmail filter that adds a label to any GitLab notification email in which you are specifically mentioned, as opposed to a notification that you received simply because you were subscribed to the issue or merge request.
Search for @your_gitlab_username in Gmail
Click the down arrow on the right side of the search field
Click "Create filter with this search"
Check "Apply the label:" and select a label to add, or create a new one, such as "Mentioned"
Check "Also apply filter to matching conversations."
Click "Create filter"
If your username on dev.gitlab.org is different from your username on GitLab.com, you might want to create a similar filter for that username as well.
If you use the archive function you normally return to your overview. With auto-advance you can return to the next message. Enable 'Auto-advance' in the labs section under settings. The default setting of showing the next older message is OK.
Set up an email signature which includes your full name and job title so people can quickly know what you do.
In Chrome Hangouts tends to consume 100% of CPU due to use of the vp9 codec. On MacOS switching to Safari solves this since it will use h264 that is hardware accelerated.
Hangouts on air
Hangouts on Air probably only works with a maximum of 15 people for scheduled calls (same limit as normal Google Hangouts).
Potential problem: even when I logged in as GitLab and got the bar below the call, I could not switch it too on-air! I did notice that the time was not properly set (anymore?). I did a test event before and that seemed to work OK. I'll try one more time to see if it works.
Potential problem 2: the video showed up as listed by default
Go to My live events on YouTube and switch to the GitLab account on the top right (you need to be a manager of our YouTube channel).
Go to => life streaming => events and create a new one with the attributes:
type => quick (using Google Hangouts on Air)
advanced: promotions: disable both checkboxes
time needs to be set correctly
The view on watch page URL only allows for people to watch it. Window that pops up when you press the start hangout on air button has the proper URL that you can send to other people and/or add it to the calendar invite, it is structured like: https://plus.google.com/hangouts/_/ytl/LONGHASH. When people join the event they have to accept a warning.
Completed live events will show the video and you can click the image to view it. You can use actions to make it public here
BTW Trying to set this up via Google+ via Hangouts on Air instead of via YouTube doesn't seem to connect to the right YouTube channel, even if you selected the right account on the top right.
[Appear.in] (https://appear.in/) allows you to instantly create a free video chat room for up to 8 participants with no login and no installation. It also offers a free reliable mobile video conference app.
One Tab (Free) tames tabs into a list which can be sorted and exported.
Quitter (Free) will switch off apps for you after some period of inactivity. Consider using this to hide Slack after a while to reduce your urge to check new messages all the time.
TripMode ($7.99) lets you control which apps can use the internet. Especially useful when you're working on a cellular/metered connection.
Check which process occupies a given port
When the GitLab Development Kit cannot start using the ./run command and Unicorn terminates because port 3000 is already in use, you will have to check what process is using it. Running sudo lsof -i -n -P | grep TCP | grep 3000 will yield the offender so this process can be killed. It might be wise to alias this command in your .bash_profile or equivalent for your shell.
If you install MobileDay (Free) on your phone and give it access to your Google Calendar it can dial into conference calls for you. It is very good at detecting the number and password from the calendar invite.
In the menu bar (next to the apple logo), click on Keychain Access
Click on Preferences
Check the box Show keychain status in menu bar
The lock icon should now show up on your menu bar
You can lock your screen by clicking the lock icon on the menu bar and clicking Lock Screen
Visual help to differentiate between GitLab servers
If you are working on multiple GitLab instances and want to have a visual differentiation, you can change the default Application theme to a different color.
How to change your username at GitLab.com
Starting point: let's say your username is old-mary and you want it to be just mary.
Note: each GitLab account is tracked by an userID, which is a number stored in a database. If we change the username, the userID does not change. And all the permissions, issues, MRs and relevant stuff within GitLab are related to your userID, not with your username.
Note: if you are not a GitLab Team member, the same process applies; except your e-mail (STEP 2), which will be different (will not be @gitlab.com email), so you can replace it with your own email account.
STEP 1: Request your new username
Access the username you want to request via https://gitlab.com/u/mary.
STEP 2: Create a new account with your new username
If support replies to you telling that the username is free to use, create a new GitLab.com account with it. Use a personal email to register your new account and choose one that has not been used with your old GitLab account.
Navigate to your Profile Settings > Emails, and add a new email. ⭐️ Trick ⭐️ If your email at GitLab is firstname.lastname@example.org, add the new email as email@example.com: this is a Gmail trick! All your emails sent to this alias will end up in your GitLab email account. 😃
Look for your username. This operation has to be done quickly, otherwise you are risking to loose your awesome new username to someone else quicker than you. We need to swap the usernames between both accounts, so you'll keep all your history, your privileges, issues and MRs assigned to you, etc.
If you work with 2 monitors, open each browser on one monitor. If you don't, open them in parallel, so that you can keep an eye on both at the same time.
Rename your new username mary to something like mary-1 and DO NOT click update username yet. Rename your old username old-mary to your new username mary and don't update that either. Just leave them typed into the boxes.
Make sure you did the previous step right!
⚠️ CRITICAL ⚠️ Update the first one (mary to mary-1). Immediately, click update on the other one (old-mary to mary).
Immediately, rename the mary-1 to your old one old-mary and click update username again.
STEP 4: Move your projects (or not)
Now, if you have any personal projects, you might want to import them to your new account (the one that has your old username now). To do that, in your new account (the one with the old username), click Create a New Project, give it the very same name as the original one, click Git - add repo by url, and paste the https:// url of your project there. To make things easier, make sure all the projects you want to import are set to public view. You can make them private afterwards.
If you have GitLab Pages projects with the default GitLab.io url, you will need to import them to you new account, then make a change to trigger a build and redeploy your site. They will be affected only if you're using a CNAME with a subdomain instead of an A record. This won't affect Pages projects that use custom domains, as they all point to the same Pages server IP via A record. Your groups won't be affected either, as they operate under their own namespace. Add both users as members of your groups and nothing changes.
That's it! Don't forget to update your username on the team page and on the Marketing Handbook, in case you're a Marketing Team member.
This is a guide on what you'll need to install and run on your machine to get Git up and running so you can create your first merge request in minutes! Follow the numbered steps below to complete your setup.