Website Handbook

On this page


Serve the needs and interests of our key audiences:

  1. Users of GitLab: software developers and IT operations practicioners.
  2. Buyers of GitLab: IT management, software architects, development leads.
  3. Users of and contributors to OSS on

Generate demand for GitLab by:

  1. Showcasing the benefits of the most important GitLab features and how they can save time and money.
  2. Compare GitLab vs competing products.
  3. Provide customer case studies which illustrate 1 and 2.


When referring to the GitLab marketing site, and the are not included.



A topic is an industry trend, theme, or technology related to GitLab and our customers. For example, DevOps, GDPR, Containers, etc. Topic pages on our website educate the reader about the topic and share GitLab’s point of view while providing additional links to resources related to that topic. These pages are intended to attract search traffic.

Topic pages should exist at the root level of the website without being nested inside of another directory. e.g. /continuous-integration

Examples of other companies who have topic pages:


A solution is a combination of products and services that solve a business problem. For example, accelerating software delivery, enabling remote teams, ensuring compliance, etc. Solution pages on our website show the application of GitLab capabilities and services to address a business problem while providing additional links to resources related to that solution.

Solution pages should be nested inside of the solutions directory. e.g. /solutions/continuous-integration

Examples of other companies who have solutions pages:

Product section

The product section of our website has pages that describe what GitLab does and the value provided. The functionality of GitLab is ordered in a hirearchy with 4 levels: Stage, Categories, Capabilities, and Features. You can find details on the Product Categories Handbook

Category pages should be nested inside of the product directory. e.g. /product/continuous-integration

Examples of companies who have product/features pages:


Similiar content can appear as a topic, solution, and in the product section with different emphasises on each page. For example continuous integration:

Ownership and responsibilities

The marketing site is an important part of our company requiring close coordination and collaboration across multiple teams. Below details which functional group is primarily responsible for which areas of the marketing site.

Marketing Site Product Manager

Luke Babb is responsible for scheduling tasks and allocating various team members to accomplish tasks.

Content Marketing

Product Marketing

Growth Marketing


Design works with our partner agency, AtreNet, during this stage

Frontend Development

Design works with our partner agency, AtreNet, during this stage

All Product Managers

Technical Writing

Updating the Marketing Website

Minimum Website Updates

Use MVCs to update the website. A webpage only needs a title and a few lines of text to be valueable. Create new pages and add the minimimal ammount of content. You can add images and more content in iterative steps.

Creating a new page

To create a new page you for follow these steps:

  1. Create an issue in the website repo Note: Don't branch from other repos like the marketing repo.
  2. Create an MR from the issue by clicking on the "Create Merge Request" button. This will create a new branch for you and link it to your issue and labe the the MR as WIP:.
  3. Click on the name of your branch after "Request to Merge" to open that branch in the repository file view.
  4. Open the source folder. This is where webpages are stored.
  5. Click on the directory where you want your webpage to be. For example, if you put a page in the source folder it will show up at the "root" level, if you create the new directory inside of another directory it will will appear at that path.
  6. Click to add a New directory from the plus sign drop down.
  7. Name the directory in all lowercase with dashes-between-words for what you want the path of your page to be. For example if you want to create a page at then click on the solutions directory and inside the solutions directory create a new directory called cloud-native.
  8. Click to add a New file from the plus sign drop down
  9. Name the flie
  10. Add this code to the top of the file
layout: markdown_page
title: ""
## Subheading

Here is your first paragraph replace this text. 
  1. Inside the quote add the title of your page. For example the title of my cloud native page would be "Building Cloud Native Applications With GitLab".
  2. Using markdown you can add more content to the page. All you need is a title, subheading and a pagraph to get started.
  3. Delete the .gitkeep file. This is a placeholder file from when you created the directory since git cannot track empty directories. A quick way to delete the file on the corret branch is to click on "edit" in the changes tab of your MR. This will open the file editor. click "cancel" and dismiss the popup that says "all changes will be lost". This will then place you in the file view for the .gitkeep file on your branch. Click the "delete" button to delete the file.
  4. ProTip: Now that you no longer have a branch with no changes you can use the Web IDE to make further edits. (The Web IDE doesn't work if you have a branch with no chages. Fix coming in 11.3
  5. ProTip: Add a link to the bottom of your page so people can continue reading releated content. Popular choices would be /product , /solutions, /pricing or any pages related to your page.
  6. If you need help you can Ping @williamchia or @jareko in the MR or on slack in the #website channel.

updating an existing page

  1. Click on the "edit" button at the bottom of the page.
  2. Edit the page. Note: page content can be in markdown, haml, or possibly in a separate .yml file that populates fields in the haml file. The hello bar is an example of content in a .yml file.
  3. If you need help you can Ping @gl-website in the MR or ping @website-team in the #website slack channel.

Requesting Website Updates

If you'd like to propose new changes to the webiste and the update is more complicated that you can do on your own to either create a new page or update and existing page you can request help from the Website team.

  1. To request help from the website team to update the site, create an issue in the www-gitlab-com project
  2. add the Website Design label
  3. ping @gl-website in the MR or ping @website-team in the #website slack channel.

Editing the homepage promo banner (hello-bar)