Serve the needs and interests of our key audiences:
Generate demand for GitLab by:
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.
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.
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.
Examples of other companies who have solutions pages:
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.
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.
/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 Digital Marketing Programs 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/
Similar content can appear as a topic, solution, and in the product section with different emphases on each page. For example continuous integration:
/continuous-integrationwould talk about what CI is at a functional level.
/solutions/continuous-integration. would talk about why CI is important for businesses to adopt.
/product/continuous-integrationwould talk about the capabilities and features that are part of GitLab's CI functionality and the value it has.
Everyone can contribute to the marketing website. While the Strategic Marketing and Pipe-to-Spend 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.
HPfor the homepage. If you have an update to any of the pages in the
Doingcolumn contact @lbanks. More details on CRO and testing in the Online Growth Handbook section
cta-btnin their class. looks for this value to fire Google Analytics events and without it we won't be able to see how visitors interact with our CTAs.
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"
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.
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 Digital Marketing Programs team for suggestions in your Merge Request. We have a list of high priority topics and recommended keywords to use.
Here's a video that shows a typical workflow to update the website
To create a new page you for follow these steps:
sourcefolder. This is where webpages are stored.
sourcefolder it will show up at the "root" level, if you create the new directory inside of another directory it will appear at that path.
New directoryfrom the plus sign drop down.
solutionsdirectory and inside the
solutionsdirectory create a new directory called
New filefrom the plus sign drop down
--- layout: markdown_page title: "" --- ## Subheading Here is your first paragraph replace this text.
.gitkeep. Delete the
.gitkeepfile. 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
.gitkeepfile on your branch. Click the "delete" button to delete the file.
/pricingor any pages related to your page.
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.
haml, or possibly in a separate
.ymlfile that populates fields in the
hamlfile. The hello bar is an example of content in a
Great care should be taken whenever moving pages on the website. Ideally, pages should never be moved without implementing an immediate 301 redirect.
The Digital Marketing Programs team can follows this process to create 301 redirects.
If you need to rename a page (e.g. change
/company/culture/all-remote/hybrid-remote, as was achieved in this merge request), follow the below steps if using Web IDE.
Within Web IDE, navigate to the directory that needs renamed, and click the option drop-down to select Rename.
Rename the folder, then click Rename folder.
Add a relevant commit message and submit a merge request.
Within the newly created merge request, edit
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: '='
When adding an image to a webpage, be sure that you optimize the image first.
team.ymland create an MR
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.
They are also used by the automated triage operation "Stage and group labels inference from category labels".
Below are attributes that can be added to a stage in
groups.<group_key>.feature_labels: A list of all the feature labels that are associated with this group. Ideally, feature labels should be associated with a category instead (see
feature_labelsin the "Category attributes" section below). This list is used in the automated triage operation "Stage and group labels inference from category labels".
Below are attributes that can be added to a category in
stub: the name of the category in lowercase/snakecase with no abbreviations. E.g. "Authentication and Authorization" becomes
authentication_and_authorization. (Don't abbreviate as this stub is used to create URLs so the full words become SEO keywords).
name: the name of the category in quotes
stage: what stage the category belongs to.
label: The category label in the
gitlab-orggroup. By default, the category label is inferred from its name. For instance, the
Code Analyticscategory is represented by the
Category:Code Analyticslabel in the
gitlab-orggroup. This attribute allows to override that. For instance, the
gitlab-orglabel for the
Kanban Boardscategory is
feature_labels: A list of all the feature labels that are associated with this category. This list is used in the automated triage operation "Stage and group labels inference from category labels".
marketing_page(optional): the path of marketing page for the category. If you include a
bodysection, then a marketing page will be auto-generated at
documentation(optional): the URL of the docs page for the category.
direction(required): the URL of the category direction page. Optionally could be the URL of an issue, epic, or issue label search query if a direction page has not yet been created.
description: a short description of the category.
true | falseshould this category appear in the ROI calculator. (omitting the line is the same as
available: an ISO date for when the feature was or will be available.
viable: an ISO date for when the category will/did move from minimum to viable on the maturity handbook page.
complete: an ISO date for when the category will/did move from viable to complete on the maturity handbook page.
lovable: an ISO date for when the category will/did move from complete to loveable on the maturity handbook page.
maturity: the current maturity of the category on the maturity handbook page. Valid values are
marketing = true, a value of
plannedwill cause the category to appear in the "coming soon" section of the homepage, while other values will cause it to appear in the "Since 20XX GitLab added" section.
marketing: A value of
truewill cause this category to appear on our marketing pages, in addition to our handbook. For the home page, a
maturitystate is also required. Internationalizaion is a good example of a category the engineering team works on, but is not a "customer-facing category" that appears on marketing pages.
body: content added in markdown will be auto-generated and turned into a page at
/product/<category>/. Features and missing features sections are automatically added to the generated category pages based on what category a feature belongs to in
features.yml. c.f. Project Management (and auto-generated page from the
categories.yml) with Continuous Integration (a custom page.)
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.
maturitywhich represents the current maturity of the category
lovablewhich are set to ISO dates when we achieved, or plan to achieve, the given maturity.
To change or update the current maturity, set the
maturity field to the desired value:
planned (or empty),
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.
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
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.
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 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.
To update the responsible person for a role, follow these steps:
source/data/stages.ymlat the relevant position e.g.
pm: John Doe.
Here's an example Merge Request.
All features and capabilities are listed in a single yaml file
features.yml) under the
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:
screenshot_url: 28-group-milestones.pngJust put the filename of the screenshot. Feature screenshots must go in the the following directory: 'images/feature_page/screenshots/'.
falseis this feature or capability available in this tier?
falseis this feature or capability available on GitLab.com? Because GitLab.com tiers map 1:1 to self-managed tiers setting this will automatically assign the GitLab.com tier. E.g.
GitLab.com Free. Adding a tiers fields is what powers the tier badges on product pages and comparison pages, as well as powers the tier feature comparison of the pricing page.
devops_tools:section such as
blackduck:, etc. that does or does not have this feature. Holds a value of either
partiallyor is blank (indicating subfields with details should exist).
partially: Examples of
partiallyare if a DevOps tool has some but not all of the feature described, or if they have the feature, but only through a plugin. If using
partiallyit is highly recommended to instead add
detailsas to what partially actually means (see next)
valid: Same as
details: A short statement about the details that need to be shared. For example: "supports 11 languages", or "only supported through 3rd party plug-ins"
false: this option was created when the pricing page used to be called the "products" page. Setting true cause the feature to show up on the pricing page. Only a limited number of the most important capabilities should be shown on the main pricing page to keep it easily consumable. Folks can click on "see all features" to see the full list of features (self-managed comparison, GitLab.com comparison).
- 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:
/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:
devops_toolssection add a tool.
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.
.md) file that will be embedded on the page. Here is where you can add more robust content about the tool. Please use the template under
/source/devops-tools/misc/tool-template.html.mdand store your new file under
|) then add content in markdown indented on the next line. Be sure to add on additional empty line after your content.
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
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'
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).
tool idand then
partiallyto indicate support for the feature (what does partially mean?) Add the same details for gitlab tiers. Adding a tool id to a feature is what causes it to show up on the comparison page for that tool. (e.g. if you don't want a feature to show up on a comparison page remove the tool id line from that feature.)
- 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
If you followed the above step, the new comparison page should be reachable
/devops-tools/tool-vs-gitlab.html and you should see it on the
devops-tools table on the main page.
The last thing you need to do is create the PDF. Follow the info in creating comparison PDFs.
/resources section of the website contains downloadable files and links to helpful content.
- 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
Uploading a PDF: If the resource you'd like to add is a PDF, it can be uploaded to
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.
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 see Requesting Website Updates to submit a proposal for new resource type(s).
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.
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.
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 division README pages are linked below for context. Let these serve as a guide and inspiration as you create your own.
readmes) within your division's handbook section first, then create your username directory within
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.
If you'd like to propose new changes to the website 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. New changes or updates with a due date should be requested at least 2 weeks prior to that due date.