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

Marketing Website Handbook

  1. You are here:
  2. Handbook
  3. Marketing
  4. Inbound Marketing Handbook
  5. Digital Experience Handbook
  6. Marketing Website Handbook

GitLab's Marketing Website (about.gitlab.com) is led by the Inbound Marketing Team and anyone can contribute. Please visit the repo to file issues and make merge requests.

The DRI for the the Marketing Website is Danielle Morrill, and internal GitLab team members can drop questions in Slack at #website

Metrics

Specific targets can be found here

Objectives

Serve the needs and interests of our key audiences:

  1. Users of GitLab: 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.

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.

Scope

The GitLab marketing website, or simply the "GitLab Website" refers to all of the content on https://about.gitlab.com except the blog and handbook.

The website does not include

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.

Pages supported by Strategic Marketing

The Growth Marketing team supports the design, development, and strategic integration of the following pages with content from Strategic Marketing. You can see the performance of these pages in the Strategic + Growth Marketing dashboard.

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:

Ownership and responsibilities

Everyone can contribute to the marketing website. While the Strategic Marketing and Inbound Marketing teams have primary responsibility over the website, the goal of these teams is to build systems, structures, and processes and empower everyone to contribute. Below is a breakdown of the ownership between Strategic Marketing and Pipe-to-Spend.

Website team

Inbound Marketing

Requesting Support

If your team is unable to update the marketing website, or you need additional levels of support from the Digital Experience team who are responsible for about.gitlab.com, then this section is for you.

Set yourself up for success
Lead time

Requests should be made with sufficient lead time to process the request, allocate resources, iterate, and produce related items.

The time needed for your webpage request will vary on a number of factors, including, but not limited to:

Create a support issue

Please fill out one of these Issue Templates to request support. Please note that if these are not filled out then we won't have the information needed to support your request.

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

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 marketing 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 marketing 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.

@gl-website

If you are seeking assistance or need the attention of the website team, please include @gl-website in the issue description to ensure the website team sees it. The @gl-website handle is a group in GitLab that the website team uses to be notified of issues and merge requests from others. For community contributed merge requests, this happens automatically with gitlab-bot and you should see an automated message saying that the website site has been notified of your merge request.

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/marketing/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/marketing/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/marketing/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
  1. 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.
  3. If you need help you can Ping @gl-website in the MR or ping @website-team in the #website slack channel.

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 team.yml
  2. Edit team.yml and create an MR
  3. The org chart is built automatically based on slug and reports_to lines.
  4. See the team structure page for more info on specialties, expertise, and mentorship availability to a listing.

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/
  screenshot_url: 'images/feature_page/screenshots/28-group-milestones.png'
  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:
  screenshot_url: ''
  solution:
  category:
    -
  gitlab_core:
  gitlab_starter:
  gitlab_premium:
  gitlab_ultimate:
  gitlab_com:
  github_com:

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. All you need to do is add a tool to the devops_tools section and add that tool id to some features and the page will be created.

To add a new comparison page:

  1. Edit features.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.

Creating and publishing your GitLab README

As part of GitLab's transparency value, we encourage each GitLab team member to consider adding a README — a great tool for transparently letting others know what it's like to work with you, and how you prefer to be communicated with.

Purpose of READMEs

When people are working together for the first time, there's a certain amount of mental and emotional energy exerted in getting to know someone. You're simultaneously doing the work, while trying to confirm or challenge preconceived notions about how a person prefers to be communicated with.

On an individual level, this requires a person to project the ideal version of themselves into each meeting, as it is assumed that this projection is the only meaningful way for another person to understand who they are and how they prefer to communicate and work.

READMEs provide a genuine report on how a person works, reducing bias/assumption and enabling people to work together based on a common framework.

GitLab team README examples

GitLab division README pages are linked below for context. Let these serve as a guide and inspiration as you create your own.

How to create a GitLab README

  1. Copy the README-template and paste into your favorite Markdown editor. If you do not have a Markdown editor, Typora and Bear are recommended.
  2. Fill out the recommended sections. Note that each section is optional. You can remove those you aren't comfortable filling out, and add sections that are germane to you.
  3. Once complete, you'll need to create a new page and a subsequent merge request to add the page to GitLab's website.
    1. If your division already has a page to host READMEs (see above), follow the guidelines to add a new page within that directory (e.g. Darren M., a member of the marketing team, would add a new directory and page within /handbook/marketing/readmes, creating /handbook/marketing/readmes/dmurph)
    2. If your division does not yet have a holding page for READMEs, follow the guidelines to add a new page (readmes) within your division's handbook section first, then create your username directory within readmes.

Making your README visible

Once your README is created, consider adding a link to it in the following places.

This provides maximum visibility to others, so that they may ingest your README in advance of working with you. This allows them to take your working style and communication preferences into account, ideally increasing the overall level of empathy expressed.

READMEs are particularly powerful when working with those outside of GitLab, who may be unfamiliar with our values. A README is a beacon of transparency, and helps set the tone for any working relationship.

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?

This is potentially due to cookiebot. 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.

Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license
View page source — Edit in Web IDE — please contribute. Creative Commons License