GitLab Professional Services
Accelerate your software lifecycle with help from GitLab experts
Popular GitLab use cases
Enterprise Small Business Continuous Integration (CI/CD) Source Code Management (SCM) Out-of-the-box Pipelines (Auto DevOps) Security (DevSecOps) Agile Development Value Stream Management GitOpsGitLab Professional Services
Accelerate your software lifecycle with help from GitLab experts
Popular GitLab use cases
Enterprise Small Business Continuous Integration (CI/CD) Source Code Management (SCM) Out-of-the-box Pipelines (Auto DevOps) Security (DevSecOps) Agile Development Value Stream Management GitOpsThis is a guide on what you'll need to install and run on your machine so you can make edits locally. This is quicker than in the web interface and 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 here /source/handbook/
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:
git --version
.Ruby Version Manager (RVM) is a command-line utility that allows you to easily install and switch between different versions of the Ruby programming language, which is used to build this website. It can be installed directly from a command prompt (e.g., in macOS Terminal) with the following command:
curl -sSL https://get.rvm.io | bash -s stable
Once RVM has been installed, ensure that your updated terminal environment has been loaded by closing your terminal window and opening a new one.
The version of Ruby that you'll need to build this website will change from time to time, but you can always check what version that is by looking at the contents of .ruby-version
in the root of the www-gitlab-com
directory. You can always check it on GitLab even if you haven't yet cloned your own local copy of the repository.
If .ruby-version
specifies version 2.6.5
, you can install it with RVM like so:
rvm install 2.6.5
to install Ruby
(enter your system password if prompted).rvm use 2.6.5 --default
to set your default Ruby to 2.6.5
.ruby --version
to verify Ruby is installed. You should see:
ruby 2.6.5p114 (2019-10-01 revision 67812)
.gem install bundler
to install Bundler.git clone git@gitlab.com:gitlab-com/www-gitlab-com.git
to clone the website. If you prefer using https, then execute: git clone https://gitlab.com/gitlab-com/www-gitlab-com.git
, but 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. 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.bundle install
to install all gem dependencies.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
.== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
.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.
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 second 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.
- Test image in color and black-and-white (you will add the color version).
- The image file should be located in the folder
sites/marketing/source/images/team/
- Name file
yournameinlowercase
and add the appropriate file extension.
https://about.gitlab.com/job-families/engineering/support-engineer/
use /job-families/engineering/support-engineer/
. Refer to other entries for reference.No
on BambooHR 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
.job_families.yml
and use command-F
(macOS) or ctrl-F
(*nix) to search for your job title.reports_to
lists your manager using the slug
value from their team page entry.reports_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
.@
.locality
to your city and your state, province, or region.story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a reference.Important: 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.
Commit
button in the bottom left. It should say something like 2 unstaged and 0 staged changes
. This will bring up a sidebar with an Unstaged
and Staged
area.Stage
button in the upper-right of the changed file view to stage each one individually. You should now see 0 unstaged and 2 staged changes
.Create a new branch
. Name the branch in the format of yourinitials-add-YOURNAME-to-team-page-date
or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06
Start a new merge request
checkbox. Then click Commit
once more.Delete source branch when merge request is accepted
box to cleanup your merge request when complete. Click Submit merge request
to submit the MR for review.+
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/marketing/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
.job_families.yml
and use command-F
(macOS) or ctrl-F
(*nix) to search for your job title.reports_to
lists your manager using the slug
value from their team page entry.reports_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
.@
.locality
to your city and your state, province, or region.story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a reference.Important: 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.
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
submit merge request
At the upper right of the new page, click edit
next to Assignee
and also assign the merge request to your manager.Note: This method may take longer than other methods, because it requires git clone
for around 4GB size repository.
sites/marketing/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
.job_families.yml
and use command-F
(macOS) or ctrl-F
(*nix) to search for your job title.reports_to
lists your manager using the slug
value from their team page entry.reports_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
.@
.locality
to your city and your state, province, or region.story
. Use other team members' stories as a reference.remote_story
, using other team members' remote stories as a reference.Important: 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.
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
README.md
.--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 to the Team Pets page. You can follow these instructions for adding 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/marketing/source/images/team/pets
.⋁
icon next to the pets
directory and choose upload file and choose the photo you prepared in step 1.data/pets.yml
and click on it to open the editor.Commit
button in the bottom left. It should say something like 2 unstaged and 0 staged changes
. This will bring up a sidebar with an Unstaged
and Staged
area.Create a new branch and merge request
. Choose a branch name of your choosing. Remember to name it something unique. We recommend the format your initials-team-page-update-yourdepartment-the date Example: mh-team-page-update-custsupport-feb06
The Web Integrated Development Environment (IDE) is used to make changes within the browser. This method requires no setup.
Edit this page
button at the bottom of the page.Web IDE
button on the right side.Commit...
button in the bottom left to review the list of changed files. Click on each file to review the changes and click the tick icon to stage the file.mh-team-page-update-custsupport-feb06
.Remove source branch
.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.
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.