This is a guide on what you'll need to install and run a local development environment on your machine so you can make edits locally. This allows you a better overview and preview when making complex changes.
Once you're set up, you will find the source files for the GitLab Marketing Website and GitLab Handbook in the www-gitlab-com
repository
However, when you only need to make small or quick changes, the Web IDE may be easier or faster than the local development environment.
If you work for GitLab Inc., we don't expect you to figure this out by yourself. If you have questions, ask anyone for help or post in the #handbook Slack channel. You're more likely to have success with:
This method involves running a single ZSH script which will complete all of the setup steps below for you.
Note: This script will only work on MacOS
rvm
or rbenv
, you will want to first uninstall it by following the instructions herecd
to the repo and directly run scripts/setup-macos-dev-environment.sh
. Otherwise, if you've never set any of this up before…/bin/zsh -c "$(curl -fsSL https://gitlab.com/gitlab-com/www-gitlab-com/-/raw/master/scripts/setup-macos-dev-environment.sh)"
and paste into your terminal.This script clones the www-gitlab-com
repo to your local machine using SSH by default, but that could fail and fall back to HTTPS. If you have added an SSH key to your GitLab account, you should switch your local repo from HTTPS to SSH.
To switch your local repo from HTTPS to SSH, run the following in your local www-gitlab-com
repo:
git remote set-url origin git@gitlab.com:gitlab-com/www-gitlab-com.git
See the GitLab SSH docs for more information.
command not found: brew
and/or command not found: asdf
even after re-runs. In that case, please enter the following commands to correct:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ${HOME}/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
yarn not found
even after re-runs. In that case, please enter the following commands to correct from the www-gitlab-com
repo which was checked out:
nversion=$(cat .tool-versions | grep nodejs | cut -d " " -f 2)
asdf install nodejs $nversion
asdf global nodejs $nversion
An error occurred while installing eventmachine (1.2.7), and Bundler cannot continue.
even after re-runs, this is usually seen with M1 MacBooks. In that case, please enter the following command to correct in your local www-gitlab-com
repo:
gem install eventmachine -v '1.2.7' -- --with-ldflags="-Wl,-undefined,dynamic_lookup"
#handbook
on Slack for assistance.(Note: This step can be skipped if you used the 'single script setup method' above)
git --version
.(Note: This step can be skipped if you used the 'single script setup method' above)
There is more than one way to install Ruby. Using a version manager can make it easier to upgrade as the required version for this project changes. It also prevents problems associated with different operating systems and their included version of Ruby.
There are three common version managers in use with this repository: asdf, rbenv, and rvm. There are ongoing conversations about which, if any, should be the default tool for the www-gitlab-com
repository. If you just need to edit this website and you really don't care about all the nuance, you can get by just fine with the rbenv instructions.
Any of these three options is perfectly suitable, but you should only choose one. The next sections include installation instructions for each. For the most part, we will not include specific commands or instructions, but rather link to the official documentation for each tool. That way, our documentation won't become out of date as tools change their workflows. However, if you are having trouble following along, please reach out in the #website Slack channel, or submit an issue to this repository with questions and problems.
.ruby-version
.asdf install ruby <version-from-.ruby-version>
in your terminal. Replace <version-from.ruby-version>
with the number in .ruby-version
, as mentioned in the previous step.In some distributions you may get the following warning when running the rbenv-doctor
script:
You seem to have multiple rbenv installs in the following locations.
Please pick just one installation and remove the others.
/usr/bin/rbenv
/bin/rbenv
This is most probably a false positive in the rbenv-doctor
script. It turns out in many Linux distros (e.g. Ubuntu starting from Ubuntu 19.04, Fedora starting from Fedora 17) /bin
is actually a symlink to /usr/bin
. So, these would be the same installation and not different ones. This can be confirmed by running ll /bin
(or ls -alF /bin
if you don't have the ll
alias).
You may need to manually install the latest version of ruby-build
as the one provided in your distribution's package repository may be outdated and not able to install the project's required ruby version. This is known to be the case at least for Pop!_OS 21.04 (based on Ubuntu 21.04).
rbenv install
in your terminal. The required version should be automatically detected from the .ruby-version
file. This can be confirmed by running rbenv version
..ruby-version
.(Note: This step can be skipped if you used the 'single script setup method' above)
There are two ways to clone this repository: ssh
or https
. You only need to choose one.
The GitLab documentation covers how to setup SSH keys. If you haven't already done this - or aren't sure - read through the GitLab SSH docs. When you have your SSH keys added to your GitLab account:
git clone git@gitlab.com:gitlab-com/www-gitlab-com.git
to clone the website.If you prefer using https, then:
git clone https://gitlab.com/gitlab-com/www-gitlab-com.git
Note that if you've activated 2FA on your GitLab.com account, you'll need to take some additional steps to set up personal access tokens on your GitLab.com account.
If you ever want to switch between SSH and https, execute git remote remove origin
, followed by git remote add origin [..]
where the [..]
is the part that starts with git@
for SSH, or with https:
for https.
cd www-gitlab-com
to change to the www-gitlab-com directory created when you cloned the repository.bundle install
to install all gem dependencies.yarn install
to install all JavaScript dependencies.git pull
) new dependencies might be required. You can execute the bin/doctor
script to check your ruby version, bundle, and yarn, and receive suggestions for updating these.Git is able to automatically convert line endings between CRLF
and LF
and vice versa. Execute the following command to configure Git to convert CRLF
to LF
on commit but otherwise leave line endings alone:
git config --global core.autocrlf input
If you'd like to learn more about Git's formatting and whitespace options see the "Formatting and Whitespace" section under "Git Configuration" in "Pro Git".
cd sites/handbook
(see monorepo docs for more details)NO_CONTRACTS=true bundle exec middleman
== Webpack proxy server enabled: use "http://localhost:4567" or "http://127.0.0.1:4567"
command / ctrl + p
to quickly open the file you need.Until this is automated in CI, a quick way to see if there are any invalid links inside a page is the following.
A pop-up window will open and tell you how many links, if any, are invalid. Fix any invalid links and ideally any warnings, commit and push your changes, and test again.
All internal links (links leading to other parts of the website) should be relative.
Most pages that you might want to edit are written in markdown Kramdown. Read through our Markdown Guide to understand its syntax and create new content.
Instructions on how to update the website are in the readme of www-gitlab-com.
For more in-depth details on setting up and using the local development environment, see doc/development.md.
We are happy to have you join our company and to include you in our team page! A sync will add a basic entry for you on our team page on your third day of employment at GitLab. You are invited to personalize this entry and add more information to it.
Ask anyone in the company for help if you need it - you can use either the #mr-buddies or #questions Slack channel for this purpose. There are three ways to update the website.
Choose the method below that feels most comfortable and have the following information handy:
Picture Requirements
- Crop image to a perfect square.
- Keep maximum dimension under 400 by 400 pixels.
- Use the JPEG (
.jpg
) or PNG (.png
) format.- Keep the file size below 100k. Minify using something like tinyjpg.com.
- Test image in color and black-and-white (you will add the color version).
- The image file should be located in the folder
sites/uncategorized/source/images/team/
- Name file
yournameinlowercase
and add the appropriate file extension.
@
in front of them. ie. LinkedIn: username
. (Some incorrect examples are: LinkedIn: linkedin.com/in/username
, LinkedIn: @username
.)https://handbook.gitlab.com/job-families/engineering/support-engineer/
use /job-families/engineering/support-engineer/
. Refer to other entries for reference.No
in Workday for Export Name/Location to Team Page?
you will have to find yourself by your job title instead of your name.Edit in Web IDE
data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/
(make sure you are searching within the file you want to edit by clicking on the file first), update your details:
name
if needed to your FirstName LastName
or PreferredName LastName
locality
should be left emptycountry
should be set to Remote
role
job_families.yml
and use command-F
(macOS) or ctrl-F
(nix) to search for your job title. You can search for .yml files in the Web IDE using command-P
(macOS) or ctrl-P
(nix)<a href="">Solutions Architect</a>
to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>
.reports_to
lists your manager using the slug
value from their team page entryreports_to
of your direct reports are referring to your slug
../gitlab-logo-extra-whitespace.png
, if present. The completed line should look like this: picture: yournameinlowercase.jpg
.pronunciation
for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)@
departments
is accurate. Use other team members' as a reference.specialty
expertise
story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a referenceImportant: Do not use the tab
character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.
team
folder using the path sites/uncategorized/source/images/team/
. To do this, you must first notice that you are in a file that is within the person
folder, which is within the team_members
folder, which is within the data
folder. You can close folders by clickin on the V to the left of the folder name. Once you have closed the data
folder, you will see the sites
folder 6 folders down. Open sites
by clicking the >, then uncategorized
, then source
, then images, and finally
team`.team
and choose Upload
.sites
folder and opening data
, thhen team members
, person
, and the folder containing you file; or you can notice your file tab on the top bar, and you can click on it to be taken to that file.picture
field to your filename. Delete the content that is this line after the picture:
that starts with ../gitlab
etc. Make sure to match the letter case of your picture file. The completed line should look like this: picture: yournameinlowercase.jpg
for example.Source Control
icon, as described in point 5 of Using the new Web IDE to edit the handbook.Commit & Push
button. An example title would be Updating My Team Page Entry
.Commit & Push
button.Yes Commit to a new branch
.New branch name
section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date
or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06
and press Return/Enter
.Create MR
. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.Why is this change being made?
as decribed. For this specific MR, you can enter something like: Adding my information and picture to the team page due to onboarding tasks.
Create merge request
.+
under the red line near the top of the screen.New branch
.Branch name
, name it something unique (it's temporary so don't worry too much about the exact name) like your initials-team-page-update-yourdepartment-the date and click Create branch
. Example: hk-team-page-update-custsupport-feb06
Repository
on the left side then Files
.sites/uncategorized/source/images/team
+
and choose Upload file
to upload your picture. Be sure to follow the picture requirements. Add text Add YourFirstName YourLastName to team page and click Upload file
.www-gitlab-com
.data
, and then scroll down to team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/SLUG_REPLACE.yml
(you are looking for a file that specifies your name or slug).edit
on the top right side of your screen.data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/
(make sure you are searching within the file you want to edit by clicking on the file first), update your details:
name
if needed to your FirstName LastName
or PreferredName LastName
locality
should be left emptycountry
should be set to Remote
role
job_families.yml
and use command-F
(macOS) or ctrl-F
(nix) to search for your job title. You can search for .yml files in the Web IDE using command-P
(macOS) or ctrl-P
(nix)<a href="">Solutions Architect</a>
to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>
.reports_to
lists your manager using the slug
value from their team page entryreports_to
of your direct reports are referring to your slug
../gitlab-logo-extra-whitespace.png
, if present. The completed line should look like this: picture: yournameinlowercase.jpg
.pronunciation
for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)@
departments
is accurate. Use other team members' as a reference.specialty
expertise
story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a referenceImportant: Do not use the tab
character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.
Create merge request
button.
hk-team-page-update-custsupport-feb06
(as an example from above) and the target is master
delete source branch when merge request is accepted
create merge request
At the upper right of the new page, click edit
next to Reviewer
and set your manager as reviewer for this merge request.Note: This method may take longer than other methods, because it requires git clone
for around 4GB size repository.
sites/uncategorized/source/images/team/
directory in the repository and git add
it. Be sure to follow the picture requirements.data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/SLUG_REPLACE.yml
in your favorite editor, specifically looking for the file with your name or slug.data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/
(make sure you are searching within the file you want to edit by clicking on the file first), update your details:
name
if needed to your FirstName LastName
or PreferredName LastName
locality
should be left emptycountry
should be set to Remote
role
job_families.yml
and use command-F
(macOS) or ctrl-F
(nix) to search for your job title. You can search for .yml files in the Web IDE using command-P
(macOS) or ctrl-P
(nix)<a href="">Solutions Architect</a>
to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>
.reports_to
lists your manager using the slug
value from their team page entryreports_to
of your direct reports are referring to your slug
../gitlab-logo-extra-whitespace.png
, if present. The completed line should look like this: picture: yournameinlowercase.jpg
.pronunciation
for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)@
departments
is accurate. Use other team members' as a reference.specialty
expertise
story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a referenceImportant: Do not use the tab
character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.
data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/
that you just edited, and git add
it.cd <WWW-GITLAB-COM REPO ROOT>
bundle exec rake build:team_yml
--set-upstream
option and specify remote as upstream.Note: When you test locally, the map on top of the page won't show your photo. This is because it is not populated with local data. More about how the map works. You will see your picture on the map as soon as your Merge Request is merged. Note: Searching the handbook in your local environment yields production results, so navigate directly to the team page via URL to see your changes.
Using what you learned in the steps above, consider adding your pet(s) to the Team Pets page. You can follow these instructions to add them via the Web IDE.
petname.jpg
or petname.png
. Ensure the picture size is around 400x400 (it must be square, see picture requirements).sites/uncategorized/source/images/team/pets
.pets
and choose Upload
.data/pets.yml
and click on it to open the editor.Source Control
icon, as described in point 5 of Using the new Web IDE to edit the handbook.Adding my dog Gary to the Team Pets Page
.Commit & Push
button.Yes Commit to a new branch
.New branch name
section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date
or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06
and press Return/Enter
.Create MR
. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.The Web Integrated Development Environment (IDE) is used to make changes within the browser. This method requires no setup.
Open in Web IDE
link on the top right section, above On this page; or click the Edit in Web IDE
link at the bottom of the page.Source Control
symbol on the left side (under the Search / magnifying glass symbol).Commit & Push
. The message or title should be as brief as possible, since it has a character limit. You can add more detail in the description in a subsequent step.Yes Commit to a new branch
.New branch name
section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date
or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06
and press Return/Enter
.Create MR
button on the bottom right. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.git checkout master
) and there create a new branch for your handbook edits.sites/handbook/source/handbook
. For the most part, you can locate the specific item to edit via that item's URL. For instance, this page is /handbook/git-page-update/ and its source lives in sites/handbook/source/handbook/git-page-update/index.html.md.erb
.README.md
. Keep in mind that the local server won't auto-reload when you change a page, so you'll need to restart it to see what you've done.Handbook Merge Requests should have the branch set to delete. It should not have commits set to squash. We do not squash commits because of the possible negative effects. Then assign the MR to a maintainer for review and merging.
If you recently created a Merge Request that was labeled as a Community contribution, you can fix this mislabeling issue going forward by updating the GitLab username in your personal entry in the team member directory to match the GitLab account you use for work.
Here is how you can do that:
GitLab has a lot of places you can put web content including the website, blog, docs, and the handbook. Here's an overview of where you should create a merge request to add content.
Sometimes the lines are blurry and it can seem as though there are multiple places that would be a good fit. For example, "how to" articles make great blog posts, but could be more discoverable to users if they are in the docs. Just pick one. It's better to create content somewhere than nowhere. When in doubt, start with the blog.