This page contains useful tips for working at GitLab and for various tools we use such as Slack, Zoom, and Google.
You can find more tools and tips in the following sub-pages:
old-mary and you want it to be just mary.https://gitlab.com/mary.mary@gitlab.com, add the new email as mary+something@gitlab.com: this is a Gmail trick! All your emails sent to this alias will end up in your GitLab email account 😃mary+something@gitlab.com.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 DO NOT update that either.
Just leave them typed into the boxes.mary to mary-1).
Immediately, click update on the other one (old-mary to mary).mary-1 to your old one old-mary and click update username again.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.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 in the following places:
The GitLab team-member resources project has a wiki for sharing among GitLab team-members.
It's for topics like parenting where people may want to share knowledge, but the handbook is not the best fit.
@tipyn's home office equipment and macOS setup
Link your GitLab email address to an easily recognizable photo of yourself on GitLab, Slack, and Gravatar. It is company policy to use a photo, and not an avatar, a stock photo, or something with sunglasses for any of your GitLab accounts, as we have a lot of GitLab team-members and our brains are comfortable with recognizing people; let's use them.
We have a dedicated section for that in the handbook.
ImageMagick provides the convert CLI command which can be used to resize images. Our blog images do not need resolutions higher than 1920x1080. This saves bandwidth and makes the website load faster.
On macOS, install ImageMagick with Homebrew:
$ brew install imagemagick
On Linux, use your package manager:
$ sudo dnf install ImageMagick
$ sudo apt install imagemagick
This example converts an existing image to 1920x1080 resolution and replaces it inline:
convert blogimage.jpg -resize 1920x1080 blogimage.jpg
You can also use percentage values for the -resize parameter. The convert CLI command can do more things explained in the documentation.
Mermaid is a tool that allows us to create flowcharts, graphs, diagrams, Gantt charts, etc. within GitLab! Check out the examples in the GitLab docs on how to use Mermaid.
A few additional resources that can be helpful when working with Mermaid are:
Note: When creating Mermaid charts in the GitLab handbook, you need to type three back tick symbols followed by the word mermaid before the chart, and three back tick symbols at the end of the chart.
This will enable Markdown to distinguish between .md and Mermaid.
Please reference the example Mermaid charts linked above to see how this looks live.
If you are working on multiple GitLab instances and want to have a visual differentiation, you can change the default Navigation theme to a different color.
Page counts are determined through a simple two-step process:
find source/handbook -type f | xargs wc -w from the root directory of the repository.Part of the maintainer training process is to keep track of Merge Request that have been reviewed and writing down an assessment on the review in the maintainer training issue. Manual upkeep of the maintainer training issue can be time consuming. There are tools that others have built to help with this task:
The https://about.gitlab.com site (this site!) lives in the www-gitlab.com repo.
The documentation for the site itself is in markdown documents under the
doc folder in the repo.
We have decided, for various reasons, not to include this documentation in the handbook itself.
If you are looking to do local development on the site, doc/development.md is probably the best place to start.
If you don't want to configure your local machine, there is now a new alternative option to use gitpod.io for "local" development in a cloud based environment. See doc/gitpod.md for more details.
If 2FA stops working unexpectedly (no new phone or computer) it's usually because of improperly configured date & time on either device. Make sure that "Automatic Date & Time" is enabled on both devices. If they're already enabled try toggling them off and on again to force an update. If this doesn't work, request that ITOps reset your 2FA setting.
Links for finding the settings:
For Android there's no definitive link, since most vendors have different UIs for their settings. But in the Settings-app, look for "Date & Time" and there should be a "Automatic Date & Time" toggle.
Netstat is a command line tool which can be useful to print network connections, routing tables, interface statistics, etc. One of the most common uses for netstat during troubleshooting is to display a list of open ports listening for connections.
sudo netstat -tulpn | grep -i listen
[user@gitlab ~]$ sudo netstat -tulpn| grep -i listen
tcp 0 0 127.0.0.1:5000 0.0.0.0:* LISTEN 18948/registry
tcp 0 0 127.0.0.1:9100 0.0.0.0:* LISTEN 18841/node_exporter
tcp 0 0 127.0.0.1:9229 0.0.0.0:* LISTEN 18764/gitlab-workho
tcp 0 0 127.0.0.1:8080 0.0.0.0:* LISTEN 18980/unicorn maste
tcp 0 0 127.0.0.1:9168 0.0.0.0:* LISTEN 18808/puma 4.3.3.gi
tcp 0 0 0.0.0.0:80 0.0.0.0:* LISTEN 18831/nginx: master
If you find a port already in use, you won't be able to successfully start up a service or program that utilizes that same port. Options to resolve are:
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 -iTCP:3000 -sTCP:LISTEN -n -P 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.
You may also wish to add a function in your .bash_profile (or equivalent file for your shell) like this:
function killport() {
lsof -i tcp:$1 | awk '(NR!=1) && ($1!="Google") && ($1!="firefox") {print $2}' | xargs kill
}
which you can use like so:
> killport 3000
and it will kill whatever process is currently using port 3000.
By adding this small configuration you will be able to view the git branch that you are using currently. If you are not inside a git repository, it only displays the username and the current directory.
For Bash:
Add the following lines in your .bash_profile
git_branch() {
git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}
export PS1="\u@\[\033[32m\]\w\[\033[33m\]\$(git_branch)\[\033[00m\]\$ "
Doing the following, makes the changes to get reflected in you current terminal:
source ~/.bashrc
For Zsh:
On macOS Catalina, ZSH is the default shell. By installing Oh My ZSH!, the git plugin is automatically loaded and shows the current git branch.
Another option would be:
Add the following lines in your ~/.zshrc
parse_git_branch() {
git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
PROMPT="%n@%d~%f%\$(parse_git_branch) %# "
The changes will show on the next terminal or immediately by running.
. ~/.zshrc
Use command aliases in your shell to speed up your workflow.
Take a look at these aliases and others in Sid's dotfiles project.
For example, by adding the following to your .bash_profile or equivalent for your shell, you can just type s to checkout the master branch of this website, pull the latest changes, and open the repository in Sublime Text:
alias gco='git checkout'
alias gl='git pull --prune'
alias gca='git commit -a'
alias gp='git push origin HEAD'
alias www='cd ~/Dropbox/Repos/www-gitlab-com/source'
alias s='www;subl .;gco master;gl'
After editing, you can just type gca to commit all of your changes, followed by gp to push them to the remote branch.
Note: you have to pay for these items yourself.
WorkFrom is a crowd-sourced resource of coffee shops and other such places that are remote-work friendly.
When using unsecured Wi-Fi, consider a personal VPN. We don't have a corporate VPN but consider purchasing a personal VPN if you travel for GitLab or use unknown networks often.
Remember that if your job has restrictions based upon geolocation (for example supporting customers with specific data restrictions and country-based access), a personal VPN may not be the best choice as often the VPN vendor routes traffic through other countries. If this restriction applies to you, consider tethering. Tethering is when you set up your mobile phone as a hotspot and connect your laptop up to it via Wi-Fi, avoiding the unsecured Wi-Fi network. There is more information here on the subject, and as long as your data plan supports it, you should be good to go. Double check before international travel, as it may be supported but have hidden costs.
When connecting to a network with a captive portal, most websites will not load as modern sites use HTTPS, and captive portals interrupt that process. Your device will try and compensate for this, but it can be tough to manage manually. If you have trouble, try connecting to http://captive.apple.com/ first, which is intentionally only HTTP and will load the captive portal.
Universal 2nd Factor (U2F) is a cryptographically strong 2FA (2-factor authentication) method. It is hardware-based, and is typically deployed via a USB or NFC device. The standard is open and is maintained by the FIDO Alliance.
During the authentication process, you enter in your username and your password. On systems with 2FA enabled and using U2F, the hardware token is queried. By pressing a button or tapping a sensor on the U2F device, the U2F device completes the authentication process in a cryptographically strong way. It is generally considered the most secure form of 2FA. It is also more convenient than manually entering codes generated by a TOTP application.
During the registration of the U2F device, a public/private key pair is generated, with the public key being registered with the service you will be authenticating with, and the private key is stored on a secure chip in the U2F device. When authenticating, after you've entered in your username and password, the U2F is queried via an encrypted message that can only be authenticated by the private key, so a button or sensor is pressed on the U2F device to allow the query to be completed, and the user is then granted access to the system.
YubiKey: The most popular U2F device is Yubico's YubiKey. There are a wide variety of sizes and styles of YubiKeys. Yubico (along with Google) helped develop the original U2F standard before it was moved to the FIDO Alliance. Most GitLab team members that have U2F devices have a YubiKey. It should be noted that for a long time Yubico's source code for its firmware was open source, but some of the newer versions of firmware are closed source. This has caused some concern in the security community, particularly those that prefer to use open source whenever possible.
Solo Security Key: Solokeys' Solo Security Key is growing in popularity, and while it often lags behind in certain features, it is also used by a few GitLab team members with success. The company began as a Kickstarter project, both the hardware designs and firmware source code are open source for Solokeys, and the open source nature is the reason a number of team members favor it.
Both the YubiKey and the Solo have been examined by both the security industry at large, third party audits by both keys' companies, and by the Security Team. Either company's offerings are more than suitable for use within GitLab and work fine with U2F-compatible systems.
YubiKey has had a number of security issues which are typically resolved quickly. They have a dedicated page for security advisories.
Solokeys has had a few security issues but as their website has no dedicated security advisories page one must either scan through their blog or read through the release notes on their source code repository.
In rare cases, a security issue involving a hardware token arises that requires the hardware token to be replaced as a firmware update will not mitigate the issue. This happened with Yubico in 2017.
Most of the attack models that impact the U2F tokens require physical access to the token itself. That is, the security advisories involve coding issues that can only be exploited via access to the token or the computer that the token is plugged into. This in itself makes the devices more secure.
Either device is fine for GitLab use, and there are other hardware tokens that are also decent (if you have questions, ask the Security Team in the #security Slack channel). The Security Team has looked at Yubico and Solokeys devices, and while both are secure, there are a few differences listed below one should keep in mind (current as of July 9, 2020):
What GitLab team members need to keep in mind is that if you travel with your company laptop - either on a business trip, a trip to visit family and friends in another location but you intend to keep working, or just a trip to the local coffee shop - treat the U2F token with the same level of care as a credit card. Do not leave it where it could be stolen.
If you are concerned about potentially losing your U2F hardware token, you can always purchase a second one, register it, and store it at a secure location. Sites following the U2F standard should support multiple hardware tokens. That way if one is lost or stolen, you can still use the other token.
Usage of 2FA is mandatory for GitLab team members. While it is not mandatory to use a U2F hardware token at GitLab as your 2FA solution, it is highly recommended as it is one of the most secure and convenient ways to meet 2FA requirements.
Slack now supports "Do Not Disturb Hours" so you won't be pinged in the middle of the night or while you are dealing with family matters. You can set your "Do Not Disturb Hours" by clicking on the bell at the top of the left pane in the Slack app. You also have the option of snoozing for 20 minutes or up to 24 hours. Note: Do Not Disturb can be overridden in the event of an emergency. See Slack documentation for more information.
You can browse all available GitLab channels by clicking on "Channels" on the left pane in the Slack app.
From there, you can see every channel, who created it, and how many members there are.
Feel free to ask for recommendations from other team members for their favorite channels.
Every team member is automatically added to the #company-fyi and #whats-happening-at-gitlab channels, where announcements are made and information for the entire company is shared.
There are also a few default channels that every new hire is added to, such as: #celebrations, #new_team_members, #questions, #random, & #thanks; these channels are optional, but we think they are a great place for team members to interact and get to know each other.
Slack now supports organizing channels in sections. Previously this only was possible through "Starred" channels. Navigate into the Slack preferences and select the Sidebar navigation item. Click on Create Section to create a new section on the left sidebar. You can also do that from the settings menu of each existing section.
Feel free to organize this with your most frequent used channels, or specific team grouping. You can drag and drop and also hide sections. You can for example create the info section and add #company-fyi and #whats-happening-at-gitlab as channels. Additionally, add the team section and move all related channels there.
In addition to GitLab team-members, designated groups such as the Core Team members and advisors outside of GitLab may be granted access to our Slack channels.
However, internal channels that start with #a_ will be restricted to GitLab team-members who have been invited to those channels only.
Any confidential conversations regarding our customers should be restricted only to #a_ channels.
The rationale for internal channels is that it could be a breach of many of our contracts for third parties to have knowledge of GitLab customers.
This is especially the case when third parties could be customers' competitors.
Slack allows you to set your status for your fellow GitLab team members by using your choice of standard messages such as "Away" and "Lunch" or a custom message and your choice of emoji. If you're off work for a holiday or vacation you can update your status by using PTO by Roots. This is a great way to let your team know whether you are available.
To have your Slack status automatically set to "In a meeting" based on your Google Calendar, add the Google Calendar app to your Slack account.
There are multiple ways to invite people into a Slack channel.
The easiest way is to use the invite command by typing /invite @jenny.
Avoid inviting people through a mention message.
E.g. @jenny as it can create a message that distracts others.
Quick Switcher is a great feature to know about if you want to get productive with Slack. As the name suggests, it allows you to switch between channels and direct messages quickly. Invoke it with Cmd + k on Mac or Ctrl + k on Windows or Linux and start typing the name of the person to chat with or the channel you are interested in. You can then navigate the suggestions with ↑ and ↓ keys and hit enter to select.
With lots of channels and direct messages, Slack can become overwhelming. To help keep track of activity on Slack, and to simplify the interface, consider displaying only unread conversations.
Animated images and emoji can add meaning to conversation, but they can also be distracting. If you would prefer to have static images and emoji, disable the animation. For details, see Manage animated images and emoji.
To sort direct messages and channels, open the direct message or channel and click on the star icon. For details, see Star channel or direct message.
Slack has a built-in feature to Unfurl links included in messages posted to Slack. This will post a preview of the link alongside the message. You can remove the unfurled preview of the link by hitting the "x" in the top-left of the preview. This will then prompt you to confirm removing the attachment, which you can hit "Yes, remove".
In the confirmation prompt you may also see a checkbox to "Disable future attachments from this website". As a workspace admin if you select the disable option this will denylist the link/domain across the workspace and will impact every user. If you do happen to denylist a link or a domain, they can be modified in the Workspace admin portal under Settings & Permissions.
If you are in a group direct message with multiple people, you can change it to a private channel, in order to avoid extra pings and allow additional team members to be added or removed to the channel.
The interface colors can be customized in Slack. This is especially useful when using multiple slack accounts, setting up different themes makes it really easy to differentiate them instantly. The theme selector is available under Preferences > Themes.
In order to setup a GitLab theme, send yourself the following message: #643685,#634489,#FC6D26,#ffffff,#71558f,#ffffff,#FCA326,#e24329, and press the Switch sidebar theme button.
Many applications can integrate with Slack. Recommended apps:
Slack reminders help you to remember things without having to keep it all in your head. You can set reminders for yourself or other team members. You will receive a notification at the specified time.
You can use natural language with the /remind command.
Type /remind help to get some tips.
For full information on Slack reminders see the Slack help.
There is a lot of information pertaining to Zoom, as it is a critical part of GitLab's communication. See the Zoom handbook page.
Tip: The [Google Calendar](/handbook/tools-and-tips/#google-calendar) invite is the single source of truth for the Zoom link. Avoid linking the Zoom link in Google Document agendas since those may quickly become out of date. If the zoom link changed around the start of the meeting it is OK to have it in there temporarily.
followup:actionitems.Return to add additional spaces under the existing numbered list in the document, highlight those spaces, and click the numbered list icon in the formatting bar (or press Command ⌘ + Shift + 7 on a Mac) to create a numbered list from the spaces. See video on how to add more rows to a numbered list for a quick tutorial.See also Live Doc Meetings for more Google Doc tips.
Google Analytics (GA) is an essential tool for making data-driven decisions. It receives data from both about.gitlab.com and docs.gitlab.com websites. Read through the Inbound Marketing Handbook for more information on GA.
For example, you can look at the GA data to analyze how visited is a certain page, in a period of your choice. You can also look at the GA referrals data to understand where the users are coming from and where they go when they leave a certain page.
To see the data for a specific page:
On the middle of the page, look for a search bar and paste the URL you'd like to analyze (without https://) and click on the magnifier button to search:
Note that you can use the search tool with:
/2017/, which will return the results for all the blog posts published on 2017docs.gitlab.com/ee/ci/ will return the results for all the range of pages contained in the /ci/ directoryGA will output the data about the page (or range of pages) you searched for, including pageviews, unique pageviews, and other data:
To find the referrals for a certain page, continue from the steps above.
Click on one of the website links to look at the data for a page of your choice
GA will output the referrals, including Previous Page Path and Next Page Path:
Optional: Set your picture in Google so that your picture will show where you are in a Google document (vs showing just your first intial). This will allow others to more easily follow a discussion when meeting attendees move around in a document.
Please make use of the Find a Time tab in Google Calendar, especially when scheduling events with teammates in other parts of the world:
Find a Time presents a new or existing event's time for all participants, adjusting for time zones as appropriate. To use Find a Time:
The GitLab Availability Calendar has been deprecated to allow for GitLab to scale effectively. We have created tools and tips for managing your time off.
The GitLab Team Meetings Calendar is available to all team members and can be found in your calendars list.
You can find the details for the Company Calls, Group Conversations, 101s, and other teams' meetings here, so you can attend a different team's meeting and ask questions, learn about what they're working on, and get to know the rest of the GitLab Departments and teams.
These meetings are open to everyone in GitLab.
If you are creating a new team meeting, please copy it to the GitLab Team Meetings calendar, and reach out to the People Experience team by pinging @people_exp in the #people-connect Slack channel with any questions or requests.
Please reach out to the People Experience team for any requests and changes to the GitLab Team Meetings calendar.
To add an event to this calendar:
Gitlab Team MeetingsAdd a filter to remove invites responses from your inbox with the following query:
*.ics subject:("invitation" OR "accepted" OR "rejected" OR "updated" OR "canceled event" OR "declined") when where calendar who organizer
Please click 'Guests can modify event' so people can update the time in the calendar instead of having to reach out via other channels. You can configure this to be checked by default under Event Settings.)
(This assumes you are using Google's new Calendar).
When you have accidentally deleted something from the Team Meetings calendar, you can recover it by:
We recommend you set your Google Calendar access permissions to 'Make available for GitLab - See all event details'. Team member calendars should not have access permissions set to 'Make available to public' due to the risk of sensitive data exposure and zoombombing.
Consider marking the following appointments as 'Private':
There are several benefits and reasons to sharing your calendar with everyone at GitLab:
If you'd like to share your calendar with e.g. your partner you can use the 'Share with specific people' feature and set the permissions to 'See only free/busy (hide details)':
Enable speedy meetings to automatically provide a buffer at the end of events you schedule. This thoughtfully allows participants with back-to-back events the opportunity to use the restroom or grab a cup of coffee without being late to their next function.
Add as many time zone world clock as you wish by going to Settings -> World Clock.
See the Engineering handbook for a listing of cloud resources and how to gain access to them.
We would be remiss if we didn't start this section off with this IMPORTANT message: Your default storage place for information that needs to persist and be available to others in the company should be ON THE WEBSITE/IN THE COMPANY HANDBOOK and not in Google Drive and Google Apps files!! This is from the top. This is how we operate, because Google Docs/Apps can only be found and contributed to by team members, and not by users, customers, advocates, future employees, Google handbook searches, or developers.
Having said that, there is content which doesn’t make sense to be created on the website directly (e.g. large collections of data in tables, spreadsheets for calculations, etc) or for which Google Drive storage makes sense.
When directing folks to these files in Google Drive please include name of the file in the handbook so that team members can search for it in Google Drive. If you link directly to the URL, people from outside the organization can request access, creating workload and the potential for mistakes.
It is important that we not just throw files into random or general places in the shared Google Drives. Doing so makes it harder for others to find and work with the content. Here are some guidelines to organizing the Google Drive content:
For starters, when your GitLab Google company account is created you automatically get a Google Drive with unlimited storage allocation in your own "home" directory (called My Drive). You can get to it by:
This is great for storing your own working files. As already stated, this should never be the final resting place for shared files that are meant to be used by the rest of the company (or beyond).
There are a few Google Drive repositories of GitLab shared files (there might be more, please add if not listed here):
How do you use these? You don't have to remember these URL's. To add these links to your Google Drive My Drive directory, do the following:
To really make your Google Drive easier to access, you can have your Google Drive show up on your Mac Finder as a regular drive. With this it is easier to store and view files such as videos, analyst reports (PDFs), etc.
Here's how to do this:
Use these GitLab branded form templates when creating internal or external surveys or forms. Make a copy of the form and only edit the copy; do not edit the template itself.
Computers with older CPUs (pre-2016/Skylake) may be missing hardware acceleration for VP9. In Chrome, this can cause excessive CPU due to use of the codec. On macOS switching to Safari or using h264ify (Chrome Web Store) solves this since it will use h264 that is hardware accelerated.
To check the status of acceleration on Chrome, see the "Video Encode" option in about://gpu (type the address about://gpu directly into the browsers address bar as the hyperlink will not work).
If you use the archive function, you normally return to your overview. With Auto-advance you can select whether to advance to the next or previous message. "Auto-advance" can be enabled from the Advanced section under Settings. This reveals the Auto-advance settings in the General section under Settings. The default setting of showing the previous (older) message is usually preferred.
Set up an email signature which includes your full name and job title so people can quickly know what you do.
Note: You can copy and paste the template below to use it in your own signature.
John Doe
Frontend Engineer | GitLab
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.
from:(gitlab@mg.gitlab.com) "you+have+been+mentioned+on".GitLab issues and merge requests can generate a lot of email notifications depending on your settings and how in-demand your attention is. It can be useful to apply a label to these generated emails and move them out of your immediate inbox.
from:gitlab@mg.gitlab.com.You can learn more about how to use Gmail filters to organize your inbox in Productivity Hack video. To import downloaded filter export go to Gmail => Settings => Filters and Blocked Addresses => Import filters.
Keyboard shortcuts only work if you've turned them on in Gmail Settings.
Steps below:
Here are some shortcuts you can use
List your inbox and preview mails in one view with this configuration change:
Use this general GitLab branded slide template when creating slide decks for internal and external use. Make a copy of the slide deck and only edit the copy; please do not edit the template itself.
Here are a few quick steps for updating your slide decks to match the most recent template:
Theme which will open the Themes panel (on the right-hand side).
Import theme.GitLab_Template into the search field.GitLab_Template and click the Select button in the bottom left to apply the theme to your slide deck.