Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Marketing Site Handbook

  1. You are here:
  2. Handbook
  3. Marketing
  4. Digital Experience Handbook
  5. Marketing Site Handbook

GitLab's Marketing Site (about.gitlab.com) is led by the Digital Experience Team and anyone can contribute.

The DRI for the Marketing Site is Michael Preuss, and internal GitLab team members can drop questions in Slack at #digital-experience-team

This documentation refers to GitLab Website pages that live in the www-gitlab-com repository. The Digital Experience team is migrating GitLab's Marketing Site to the Buyer Experience Repository</li>.

Objectives

Serve the needs and interests of our key audiences:

  1. Users: software developers and IT operations practitioners.
  2. Buyers of GitLab: IT management, software architects, development leads.
  3. Users of and contributors to OSS on gitlab.com.
  4. General public interest: job seekers, investors, press, etc.

Generate demand for GitLab by:

  1. Providing a compelling landing page experience for organic search traffic visitors
  2. Showcase the benefits of the most important GitLab features and how they can save time and money.
  3. Educate existing and potential GitLab customers on GitLab vs competing products.
  4. Provide customer case studies which illustrate 1 and 2.

Scope

The GitLab marketing site, or simply the "GitLab Website" refers to all of the content on https://about.gitlab.com and the contents of sites/uncategorized in the www-gitlab-com rexcept for:

See Where should content go? to learn which web property is the most appropriate place to put different types of content. To learn what section of the website different content belongs see definitions.

Known Issue: There is an ongoing issue to further clarify the DRI(s) for various parts of the www-gitlab-com repo and project, and this is a Q2 FY22 OKR for Inbound Marketing

Metrics

Tracking Tools

As of 2021-04-27, we are actively auditing the tracking, cookies, and other 3rd party personalization tools installed on the GitLab Website to ensure we are only collecting the information needed to deliver our service.

List of Tracking Tools

TBD - format will be a table with a list of tracking tools and brief description of purpose.

For example: Google Analytics web metrics

GitLab also publishes a list of all the technology that GitLab currently uses to support the business.

Definitions

Topics

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:

Solutions

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 hierarchy 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: https://mailchimp.com/features/ https://www.groovehq.com/features

Compare sections

There are two comparison sections on our website, /compare/ and DevOps tools.

The DevOps tools section provides an in-depth, feature by feature comparison of GitLab and our competitors. Pages in the DevOps tools section are maintained by the Competitive Intelligence team, which is part of the Strategic Marketing team.

Pages in /compare/ are shorter and focused on a single Call to Action that offers relevant resources to visitors arriving via paid advertising. Pages in /compare/ are maintained by Growth Marketing team and Marketing Program Managers.

Examples of companies who have comparison pages: https://postmarkapp.com/compare/sendgrid-alternative https://www.zendesk.com/support/features/zendesk-vs-intercom/

Overlap

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

Requesting Support

If you need support please review the information on the Digital Experience Hanbook Page

Updating the Marketing Website

Naming conventions

Use consistent language across the site when naming links, page names, directory names, page titles, etc. If you see inconsistent language, log an issue to correct. We use american english on the site. Here are some examples below. If in doubt, ask in the #marketing slack channel for language help.

Do use nouns when appropriate

Do use the imperative tense as much as possible

Don't use noun forms of verbs

Don't use present participle ("ing" words)

Nouns may end in "ing"

Creating new pages

Use MVCs to update the website. Create new pages and add the minimal amount of viable content. You can add images and more content in iterative steps.

All pages should use lowercase URLs to help avoid unintentional errors when linking to pages on about.gitlab.com.

We have 10-20 seconds to tell visitors why they should stay on our pages. Tell visitors what value the page will give them. Start with a high-level summary opening the page. This could be as simple as a single sentence, but we shouldn’t put the burden of discovering the value of the page on visitors.

The page title and URL should include keywords visitors might use to discover the page you’re creating. If you’re not sure what terms a visitor might use, ask the Growth Marketing team for suggestions in your Merge Request. We have a list of high priority topics and recommended keywords to use.

Website Workflow

Below, view a video that shows a typical workflow to update the website.

In the GitLab Unfiltered video below, Sarah D., marketing operations manager at GitLab, shows Wil S., social marketing manager at GitLab, how to add a new page to your section of the handbook complete with a new main page and table of contents.

Creating a new page

As an Engineer

If you are an engineer, be sure to check out our developer docs. If adding a new top level directory to the marketing site, make sure to add to data/monorepo.yml under uncategorized/paths. Docs on monorepo.

As a Non-engineer

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 label 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 sites folder. This is where webpages are stored.
  5. If this is an update to about.gitlab.com, select the uncategorized directory. If these is an update to the handbook, select the handbook directory. Once you have selected the site where you would like to make the change, choose the directory where you want your webpage to be. For example, if you put a page in the uncategorized folder it will show up at the "root" level, if you create the new directory inside of another directory it 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 about.gitlab.com/solutions/cloud-native 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 file index.html.md
  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". Save your page by clicking "Commit changes". (Using markdown you can add more content to the page. All you need is a title, subheading and a paragraph to get started.)
  2. Return to the directory you created. You will see that you now have two files: index.html.md and .gitkeep. 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 correct 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.
  3. 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 changes. Fix coming in 11.3
  4. ProTip: Add a link to the bottom of your page so people can continue reading related content. Popular choices would be /product , /solutions, /pricing or any pages related to your page.
  5. If you need help you can ask in the #mr-buddies slack channel.

Analyst Report Pages

How to create an analyst report page in 5 not-so-easy steps.

AR Part 1: Edit the analyst reports YAML

  1. Open analyst_reports.yml - https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/analyst_reports.yml
  2. Click “Web IDE”
  3. Add an entry for the new report. For example:
- url: gartner-aro19
  title: "Gartner Application Release Orchestration Report"
  subtitle: "Gartner Cites GitLab as a Challenger in MQ for ARO"
  resource_link: /resources/gartner-aro/
  include_file: /analysts/includes/gartner-aro19
  1. Edit the url, title, subtitle, resoruce_link, and include_file
    1. The incue_file should take the format /analysts/includes/<url>
      • Use the url format <analyst>-<report><year>. Make a note of this url as you'll need it later a few times throughout the process.
      • Use the official title of the report for the title
      • Subtitle - use analyst approved language
      • If we get the reprint, then uncomment the “resource” line. If not, leave it commented with a # at the beginning of the line. You need to coordinate with MPM to create a landing page to download the report to use as the resource link.
  2. Commit the change to create a new MR:
    • Click “commit”, add a commit message, and click “commit” again,
    • Add “WIP:” to the title so that it doesn't get merged prematurely ("WIP:" means "don't merge")
    • “Submit merge request”
    • NOTE: The pipeline for the MR will fail. That's OK. It won't pass until you complete the steps below.

AR Part 2: Create the include file

  1. Open the WebIDE from your MR.
    • This is a tricky step. If you don't’ open the WebIDE from your MR then you’ll be working on a different branch. Changes you make on that branch won’t show up in your MR. Alternatively, you can keep the WebIDE open in a tab and continue to make changes after you add each commit. As long as you commit to the same branch it will update on the same MR.
  2. Click on the edit tab. It's on the left under the GitLab logo and looks like </>
  3. Next to the word “edit”, click on “new file” icon (looks like a page with a plus) then add the path
    • The path will be /sites/uncategorized/source/analysts/includes/ plus the file name for the report you are adding using the .html.md file extension. <analyst>-<report><year>.html.md
    • For example: /sites/uncategorized/source/analysts/includes/gartner-eapt20.html.md
    • This should create a new empty file for you.
  4. Copy an existing include (be sure to leave in the disclaimer at the bottom)
  5. Update the content
  6. Commit that change to the MR branch

AR Part 3: Create and upload a report image

  1. Create an image of the report. Opening a PDF in Mac preview you can go to File > Export and select JEPG to save the 1stst page of the report. For example: https://about.gitlab.com/images/analysts/cloud-ci-thumb.png. This is a tricky step because what you name the file is very important. It is highly recommended that you use “kabob case” meaning all lowercase letters with dashes in between the words instead of spaces. It looks like shish kabob :)
  2. Upload the image to the /images/analysts/ folder.
  3. Open the WebIDE from your MR. This is a tricky step. If you don't’ open the WebIDE from your MR then you’ll be working on a different branch. Changes you make on that branch won’t show up in your MR. Alternatively, you can keep the WebIDE open in a tab and continue to make changes after you add each commit. As long as you commit to the same branch it will update on the same MR.
  4. On the edit tab, open the source folder, then the images folder, then the analysts folder. This is kinda tricky because you have to scroll past a lot of folders to find the one you want. The folders are in alphabetical order.
  5. Hover over the analysts folder and click on the drop down and select “Upload file”. This is an important step. If you upload the file to a different folder then the image won’t show up on the page.
  6. Choose the image and click “open”.
  7. Commit that change to the MR branch

AR Part 4: Edit the haml file

  1. Open the WebIDE from your MR. This is a tricky step. If you don't’ open the WebIDE from your MR then you’ll be working on a different branch. Changes you make on that branch won’t show up in your MR. Alternatively, you can keep the WebIDE open in a tab and continue to make changes after you add each commit. As long as you commit to the same branch it will update on the same MR.
  2. Type “t” to open up the fuzzy finder and search for the /sites/uncategorized/source/includes/forrester-reports.html.haml file. Open it in the WebIDE
  3. Copy a “section” and paste it at the top underneath .forrester-waves-container This is a tricky step because the indentation needs to be exactly the same as the other sections. When you copy you need to copy all the spaces indenting the line. When you paste, be sure to paste with your current not indented at all. This should give you the same spacing. For example: 
      <!–– Gartner ARO 2019 ––>
  .forrester-wave-row
 .wave-row-content
   = image_tag "/images/analysts/gartner-app-release.jpg", class: "forrester-wave-graphic", alt: "GitLab Cloud CI Forrester Wave thumbnail png"
 .wave-row-content
   %img.gartner-logo{ src: "/images/home/gartner-logo.svg", alt: "Gartner logo svg" }
   .text-center.forrester-graphic-title
     %p ARO Report
   %p Gartner Cites GitLab as a Challenger in MQ for ARO
   %a.btn.cta-btn.accent.margin-top20.reports-include-button-aro{ href: '/analysts/gartner-aro19/' } Read more
  4. Update the block with info from the new report. This is a tricky step because you only want to change some lines. Don’t edit any parts that start with a dot like ` .forrester-wave-row, .wave-row-content, or .text-center.forrester-graphic-title`. The phrases that start with a dot are CSS classes, so if you edit them the page will be formatted strangely.
  1. Commit your changes to your MR.

AR Part 5: Review

  1. Wait for the pipeline to complete and review your changes in the review app.
  2. You can continue to update the files in the MR. Particularly the include file will have content from the PM and the PMM. However, it is recommended to merge a skeleton page with TBD, then have the PMM open a new MR to add their changes.
  3. If it all looks good, assign to someone to merge.
  4. Pat yourself on the back for successfully completing a website update process designed for people who are software developers.

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.

Moving a page

Great care should be taken whenever moving pages on the website. Ideally, pages should never be moved without implementing an immediate 301 redirect.

The Inbound Marketing team can follows this process to create 301 redirects.

Renaming a page

If you need to rename a page (e.g. change /company/culture/all-remote/part-remote to /company/culture/all-remote/hybrid-remote, as was achieved in this merge request), follow the below steps if using Web IDE.

  1. Within Web IDE, navigate to the directory that needs renamed, and click the option drop-down to select Rename.
  2. Rename the folder, then click Rename folder.
  3. Add a relevant commit message and submit a merge request.
  4. Within the newly created merge request, edit redirects.yml.
    1. To put the redirect in place, add a few lines to data/redirects.yml. Define "sources", "target", and "comp_op" like so:
   - sources:
   	 - /company/culture/all-remote/part-remote/
    	 - /company/culture/all-remote/part-remote
      target: /company/culture/all-remote/hybrid-remote/
      comp_op: '='

Optimize images

When adding an image to a webpage, be sure that you optimize the image first.

  1. Select the image you'd like to add to a page and save a copy to your computer.
  2. Add your local copy to ImageOptim and optimize the image for the web.

Updating the team page and org chart

  1. Both the team page and org chart are updated based on your individual team member .yml file.
  2. Follow the directions to add or update your team page entry.

Updating the homepage promo banner (hello-bar)

Working with Stages, Groups, and Categories

Categories and stages are defined in the product handbook. Stages are stored in data/stages.yml and categories are stored in data/categories.yml as the single source of truth for engineering and marketing.

These two files power various parts of the website including the homepage, product pages, and product categories handbook.

They are also used by the automated triage operation "Stage and group labels inference from category labels".

Stage attributes

Below are attributes that can be added to a stage in data/stages.yml. Each of these properties is accessed via stages.<stage_key>.foo

Group Attributes

Below are attributes that can be added to a group in data/stages.yml. Groups are defined in the groups property of a stage. Each of these properties is accessed via stages.<stage_key>.groups.<group_key>.foo

Category attributes

Below are attributes that can be added to a category in data/categories.yml. Each of these properties is accessed via categories.<category_key>.foo.

Working with category maturity

There are five fields in categories.yml that control a category's maturity. These work together to define what the maturity currently is, how it has evolved over time, and our plans to improve in the future.

To change or update the current maturity, set the maturity field to the desired value: planned (or empty), minimal (available), viable, complete, and lovable. Next, ensure that the historical and future maturity values are still consistent. For example, if you incremented the maturity of the category from viable to complete, you should also set the field complete to the date of the GitLab release when it changed.

Sample template

authentication_and_authorization:
  name: "Authentication and Authorization"
  stage: manage
  documentation: https://docs.gitlab.com/ee/administration/auth/
  vision: https://gitlab.com/groups/gitlab-org/-/epics/628
  description: "GitLab features multiple auth mechanisms including LDAP (including Active Directory), OmniAuth, CAS, SAML, Okta, and Authentiq."
  roi: true
  available: 2017-10-01
  viable: 2019-05-22
  complete: 2019-12-22
  lovable:
  maturity: minimal

Proposing a change

Due to their importance and wide usage throughout the company, changes to Stages, Groups, and Categories need to be reviewed. Open a merge request using the Category-Change template to get started.

Major changes

Any change to a Stage or Group, or a significant change to a Category, is a major change. Examples of significant category changes include their names, their group membership, and presence on our marketing page.

Due to their impact, executive approval for major changes is required in addition to the PMs, PMMs, and EMs responsible. Follow the approval process defined on the categories page.

Minor changes

Minor changes to Categories are generally routine changes, like updates to maturity and content links. For example, upon shipping an MVC the maturity would change to minimal, and a link to the documentation would be added.

Approvals should be gathered from the responsible PMs, PMMs, and EMs. Also mention the relevant engineering and product directors, so they are aware of the changes. If changes are included in a release post, ensure the approval team and directors are mentioned on the MR.

Updating responsible persons for a Group

To update the responsible person for a role, follow these steps:

  1. Go to the GitLab.com / www-gitlab-com project
  2. Change the name of the responsible person in data/stages.yml at the relevant position e.g. pm: John Doe.
  3. Add the markdown reference link of the responsible person in sites/handbook/source/includes/product/_categories-names.erb

Here's an example Merge Request.

If the person is not yet listed on the team page, please follow these instructions to add them.

Adding features to webpages

All features and capabilities are listed in a single yaml file (features.yml) under the features section. It is the single source of truth for multiple pages across the website including:

To add a new feature, add a feature block to under the features: section of the page. Add the following attributes:

For example:

- title: "Group Milestones"
  description: "Create and manage milestones across projects, to work towards a target date from the group level. View all the issues for the milestone you’re currently working on across multiple projects."
  link_description: "Learn more about Group Milestones"
  link: https://docs.gitlab.com/ee/user/project/milestones/
  solution: plan
  category:
      - portfolio_management
  gitlab_core: true
  gitlab_starter: true
  gitlab_premium: true
  gitlab_ultimate: true
  gitlab_com: true
  github_com: false
  github_enterprise: false
  bitbucket_org: false
  bitbucket_data_center: false
  gogs: false
  jira:
    valid: true
    details: 'only through 3rd party extension'
  ca_agile_central: false

Copy and paste this template:

- title: ""
  description: ""
  link_description: ""
  link:
  solution:
  category:
    -
  gitlab_core:
  gitlab_starter:
  gitlab_premium:
  gitlab_ultimate:
  gitlab_com:
  github_com:

Updating content on GitLab Learn

The underlying data shown on the GitLab Learn page is available in https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/blob/main/content/learn/index.yml

To update the course content data:

  1. Open an MR to the learn.yml file. Follow the existing syntax in the file. For ease of adding a new course, we recommend copying an existing entry and updating the values based on the new course being added, populating every field.
  2. Add content to the list as soon as it is planned.
  3. To indicate that a course is planned for the future, include a live_date in the future. You can see an example in this MR #94773.

Important guidelines to keep in mind:

  1. learn.yml is our SSOT for GitLab-produced content, including all existing and future planned content.
  2. When planning new learning content, add it to [learn.yml]https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/blob/main/content/learn/index.yml) as soon as possible, at a minimum monthly, and aim to include what you plan to produce over the upcoming 6 months or more. This gives visibility to all other GitLab team members producing learning content as to what has been planned.
  3. Before producing new content, check learn.yml for redundancy, as other teams may have developed or plan to develop similar content.
  4. Communicate updates with other DRIs working on learning content by posting on the #gitlab-learn-updates Slack channel (available to team members only)

Creating a DevOps tools comparison page

The /devops-tools section of the website shows info about DevOps tools and a feature comparison of those tools to GitLab. Comparison pages are auto-generated from features.yml and devops_tools_list.yml. All you need to do is add a tool to the devops_tools section in devops_tools_list.yml and add that tool id to some features and the page will be created.

To add a new comparison page:

  1. Edit devops_tools_list.yml
  2. Under the devops_tools section add a tool.

Although the summary and include_file fields are not strictly required by the parser in order to build the page, every tool should have at least one paragraph summarizing the comparison using EITHER the summary field or the include_file field (see below for details). summary only is deprecated. Use include_file method whenever possible.

For example:

With include_file (preferred method):

  jenkins:
     name: 'Jenkins'
     logo: '/images/devops-tools/jenkins-logo.svg'
     category:
       - ci
       - cd
     include_file: devops-tools/jenkins/index.html.md.erb

With summary (deprecated method):

  chef:
     name: 'Chef'
     logo: '/images/devops-tools/chef.png'
     category:
       - infrastructure_configuration
     summary: |
       Chef is a configuration management tool that enables deployment and maintenance of state for large scale infrastructure. Chef excels as managing legacy infrastructure like physical servers and VMs. Chef was designed before widespread container adoption and does not implement Kubernetes natively.

       GitLab is a complete DevOps platform, delivered as a single application that includes not only configuration management, but also capabilities for project management, source code management, CI/CD, and monitoring. GitLab is designed for Kubernetes and cloud native applications.

       GitLab can be used together with Chef to enable VM and bare metal configuration management. For Cloud Native applications run on Kubernetes, Chef is not required and GitLab can provide all the functionality natively.

Copy and past this template:

unique_tool_id:
    name:
    logo: '/images/logos/TOOLNAME.png'
    category:
      -
    include_file: 'devops-tools/TOOLNAME/index.html.md'
  1. Add features to the comparison section.

Be sure to add features that GitLab has that the other tool doesn't and also features the other tool has that GitLab doesn't so that our comparison are transparent and honest (ie. this shouldn't be one sided).

For example:

  - title: "Free CI/CD with shared or personal Runners"
    capability: true
    description: "GitLab.com has shared Runners that allow you to use GitLab CI/CD completely free up to 2000 build minutes for private projects and unlimited for public projects. Alternatively, you can set up your own Runner for faster build processing, unlimited build minutes, or special requirements."
    link_description: "Explore GitLab.com offerings"
    link: /gitlab-com
    solution: gitlab_com
    gitlab_core: true
    gitlab_starter: true
    gitlab_premium: true
    gitlab_ultimate: true
    gitlab_com: true
    github_com: false
    bitbucket_org: 'partially'
    gitlab_ci: true
    codestar: false
  - title: "Domain Specific Language"
    description: "A Domain Specific Language (DSL) for defining infrastructure configuration allows thinking in resources, not files or commands to write declarative rather than procedural code."
    # link_description: ""
    # link: ''
    solution: missing
    gitlab_core: false
    gitlab_starter: false
    gitlab_premium: false
    gitlab_ultimate: false
    puppet: true
    chef: false
  1. If you followed the above step, the new comparison page should be reachable under /devops-tools/tool-vs-gitlab.html and you should see it on the devops-tools table on the main page.
  2. The last thing you need to do is create the PDF. Follow the info in creating comparison PDFs.

Adding content to resources

The /resources section of the website contains downloadable files and links to helpful content.

  1. To add a resource, edit the resources.yml file.
  2. To create a new entry for your resource, use this template and add it to the top of resources.yml:
- title:
  url:
  image: /images/resources/gitlab.png
  type: Pick one --> 'Blog post' 'One-pager' 'Report' 'Webcast' 'White paper'
  topics:
    - Cloud native
    - Code review
    - Continuous delivery
    - Continuous integration
    - DevOps
    - Git
    - GitLab
    - On-demand training
    - Public Sector
    - Security
    - Software development
  solutions:
    - Distributed teams
    - Accelerated delivery
    - Executive visibility
    - Project compliance
    - Security and quality
  1. Uploading a PDF: If the resource you'd like to add is a PDF, it can be uploaded to /pdfs/resources/.
  2. Selecting an image: Each resources has a thumbnail image based on their topic; select the most relevant image for the content. The current thumbnail images are shown below and can be found here. ALT
  3. Selecting a type: All resource types are listed in the code snippet above; select one that best fits your content. If the resource does not fit the current types, please submit a proposal for new resource type(s).
  4. Selecting topics & solutions: The code snippet above provides all of the current topics and solutions; chose the topics and solutions that best apply to the content. Please note they are case sensitive and incorrect casing or spelling will result in the generation of new, unwanted, topics and/or solutions.

Netlify CMS

The Digital Experience team is incrementally adopting Netlify CMS for the marketing website. It offers a more user-friendly way of editing the marketing site, but comes with some limitations:

Read the Netlify CMS handbook page for up to date directions and status of the system.

Understanding how up to date the marketing site is

If you're interested in getting a pulse on how recently the marketing website has been updated you can use a quick script to create a CSV in your local tmp/ folder with file names and their last commit date. Run it from the root directory of www-gitlab-com on your local machine:

ruby scripts/get-most-recent-commits.rb

It doesn't exactly map to URLs on about.GitLab.com, but this should be able to give you a pulse of what gets updated and how frequently. It only checks files in data/ and sites/uncategorized/ for now. For each file tracked in git in both of those folders, it grabs the file name and its most recent commit date (as known to git on your machine - so it will be incorrect if you haven't recently fetched or pulled from master).

Most of the data/ files map closely to a URL on the website. For instance, data/topic/ci-cd.yml is the data for https://about.gitlab.com/topics/ci-cd/. So you should be able to scan through the CSV and get a good sense of how recently we've updated data files.

The files in sites/uncategorized are a little more complex. Some of them are straightforward, like sites/uncategorized/source/get-started/index.html.md is https://about.gitlab.com/get-started/. Others are a little more meta, but still give you good information, like sites/uncategorized/source/includes/cms/topic/body.html.haml will tell you how recently we have updated the layout for the body partials of the aforementioned topic pages.

Getting a direct mapping of each URL and its corresponding files is possible, but not practical. The only way we can find that out is by hooking into the Middleman sitemap, which is only available to us in templates. That means we have to have a Middleman instance running (or run the build process). But getting the most recent commit date requires having Ruby run a system call to run git log -1 --format=%cd --date=short /path/to/file for each and every file. It takes a long time, and including that in Middleman somewhere would impact the overall pipeline negatively.

In the future, we could explore a custom Middleman extension that provides your data through the interface like http://localhost:7654/__middleman has for most of the other config. But it would still be as slow as the system calls take (which is about 20ish minutes for the actual entire sitemap including handbook. Closer to 5-10 minutes for just marketing).

Merge requests

For best practices regarding testing and reviewing merge requests, please see our related handbook page for reviewing merge requests.

Working in Modules

What is a module?
  1. A module is a section where the presentation, goal, and required functionality remains the same, but content can be updated (wording, imagery, links, etc).
  2. A module is a block, box, or section of the page, generally kept as small as possible. It's usually a horizontal slice of layer cake across the page but can also be a chunk of a sidebar.
  3. Modules often have configurable options to facilitate reuse with different configurations. It might not always be desirable to have a title block or buttons might need to expire after a date.
Why is it important for a module to be reusable?
  1. In order to facilitate updates, the code needs to be reusable. It's not an easy update if you have to build it again.
  2. Implementing the same thing over and over again is not an efficient use of resources.
  3. In order to keep the codebase clean, navigable, and easy to understand it's important to maintain SSOT.
  4. If the same code is implemented several times in several spots then the chance for bugs increases. One of those spots might have a bug where the others don't.
  5. Much of what goes into building code is unseen on the page. This includes things like optimizing performance, setting up tracking, preparing assets such as formatting images & videos, building responsive views and layouts, human physiology (fingers on a touchscreen, eyes and perception, etc). Testing and building all of these things takes time, so it's important to reuse and reduce code as much as possible.
Why is it important for a module to have a single-purpose?
  1. In order to facilitate updates, the code needs to be easy to operate.
  2. Having a clearly defined purpose for each module enhances the goals of the page and assists with navigation and conversion goals. If a module tries to do 5 things or there are 3 different modules on the page doing the same thing it's easy to spot.
  3. An end user might be confused if duplicate modules are on the page.
  4. If a module gets too large then it becomes harder to understand the code. Keeping a module single-purpose keeps the module small.
  5. Tracking the performance of a module becomes more difficult the more a module changes.
  6. When examining from a distance, it's hard to know what module to use if the modules all have several different purposes, sometimes overlapping purposes. "Do I use this module or that one?"

Video bands

This is a link to our documentation on how to implement a video band.

Digital FAQ

Why isn't this form working?

Why isn't this form working?

Many of our forms are served through a third party tool, Marketo. Sometimes Marketo is blocked by an ad blocker or a strict web browser such as Brave. GDPR and CCPA (among other laws) require us to obtain consent before setting cookies and those cookies are required for many third party functions.

If you are having trouble using a form, please try updating your cookie settings to allow personalization (personal information) cookies. If that does not work, please try a different browser with a less strict adblocker and ensure our domain and subdomains (gitlab.com, about.gitlab.com, and page.gitlab.com) are not blocked.

If you have tried the above solutions but are still having trouble using a form, please file a bug report. Please note that if you do not provide all of the requested information we might be unable to reproduce the bug and therefore unable to fix it.

Why can't I see something in the review apps?

Why can't I see something in the review apps?

Because of how our infrastructure is setup, certain third party content (such as youtube embeds) or advanced javascript may not appear on review apps. If you are unsure of the cause, please contact us so we can help review what might be impacting your project.

If you need to temporarily preview an item in the review app before release, you can try to add the following attribute to the frontmatter of the file: manual_cookiebot: true. Do not commit that change without removing it before your final merge. Alternately, you can follow this tutorial for steps on how to use developer tools to view a review-app video blocked by cookiebot.

What logos do we have permission to use?

What logos do we have permission to use?

On the about.gitlab.com website we have approval to use the customer logos lisited at the following link, Approved customer logos for promotion

Can I request a specific project release time?

Can I request a release time?

  • Due to how CI/CD deployment pipelines work, release times will NOT be exact. Please plan accordingly. We try to have releases live within 1 hour of the requested timeframe.
  • When requesting a release time, please specify a timezone.
  • Reasons we can't guarantee a release time include:
    • We don't have a dynamic server, all items are pre-compiled and static.
    • Pipelines might have hundreds of people already in the queue before you.
    • Pipelines might be broken.
    • It takes an unknown amount of time for pipelines to allocate resources, build, run tests, and deploy.
    • It takes time for our CDN to propagate any changes across their network.
    • We don't have dedicated QA resources to ensure that things will happen as expected.
  • If planning to release AT a specific time…
    • Request a time an hour before the expected release.
    • Plan for your item to appear before the expected release time. This might mean supplying alternate visuals or copy.
  • If planning to release AFTER a specific time…
    • Plan for the preexisting content to cover that time range.
  • Please ensure requested times are during normal business hours for the person making the changes.
    • If any changes are requested outside of their normal business hours, please ask before hand if that is possible or if someone else who is available can work on it to ensure that it releases in a timely fashion.
How do I fix a stuck merge train?

How do I fix a stuck merge train?

Sometimes a merge train will get stuck in our www-gitlab-com repo pipelines. Please see this related issue for instructions on how to recover a stuck merge train.

Open in Web IDE View source