This page contains instructions, tips, and historical recordings for non-technical team members on how to work Handbook-First. This page is intended to be complementary to Using GitLab at GitLab, and we suggest you start there if you have not yet completed the GitLab 101 Tool Certification.
Have your own practical Handbook editing tips? Drop a video below!
The Web IDE based on VS Code was released as Beta on 2022-12-19 and is the new default with GitLab 16.0. This handbook section explains a typical workflow to edit the handbook:
Please go with bias for action to add updates to this handbook page as the Web IDE development continues, and more features are added to improve the workflows. Feel free to assign @dnsmichi for review.
This video covers:
Edit this page
action using the Web IDE, overview walkthrough, editing the handbook, again creating a merge request with the same actions.Edit this page
to open the new Web IDE.
Web IDE
from the edit actions. This requires you to navigate into the source tree where the handbook files are located.Shift+Cmd+E
)Cmd+Shift+P
on macOS opens the Web IDE command palette to search for commands. For example, type Markdown
, select Markdown: Open Preview to the Side
and try the preview.
Upload new files by right-clicking and selecting Upload...
for example images into source/images/handbook/
and the corresponding file tree, following the handbook directories.
Open the Source Control
icon on the left menu which has a blue marker for counting the file changes. Tip: Keyboard shortcut Ctrl+Shift+G
.
Review the changed files, and once ready, specify a Git commit message and click Commit & Push
. Keyboard shortcut: Cmd+Enter
.
Commit the changes to a new Git branch (leave selection, press Enter
).
Specify a new Git branch name (optional). Press Enter
to continue. This action pushes the changes into the Git repository. The changes are persisted on the GitLab server and are immediately visible in the project view.
Check the pop-up at the bottom right, and click Create Merge Request
to open the GitLab MR tab. Tip: The notification bell icon at the bottom brings back the notification, if accidentally dismissed.
Fill in the MR template, provide why the merge request is created, add labels (e.g. using quick actions /label ~handbook
) and assign yourself (/assign @<yourusername>
).
Make additional changes to the MR: Select Code > Open in Web IDE
on the upper right menu. This opens the Web IDE again to make changes. All changed files are opened automatically.
Make changes, commit and push them, and select the MR associated branch again (follow this issue for UX commit flows).
Optional: Follow the pop-up notification to navigate back to the MR.
Tip: Practice the keyboard shortcuts for your workflows: After making changes, Control+Shift+G
to commit, Cmd+Enter
, Cursor to select the branch, Enter
, etc.
Note: The Cmd+w
keyboard shortcut to close a file tab in the Web IDE gets overridden by the Chrome browser to close the browser tab. This is a known problem, use this shortcut carefully.
In these videos, we run through the GitLab Handbook using the legacy version of the Web IDE (deprecated May 2023) with experts, uncovering how to best use the Handbook in our day-to-day work, and learning best-practices for Handbook editing along the way. They are meant to be helpful to understand generally how GitLab works, but the instructions cannot be followed exactly since the Web IDE used is no longer live as of May 2023.
Please note that the video mentions that you need to go to source/handbook to create a page which is no longer the case. The handbook is located under sites/handbook/source/handbook.
This video covers:
This video walks you through moving the location of a handbook page. There is a 1 min delay, so recommend starting the video at 1:03 for efficient viewing. We have seen that it may take over 24 hours for the move to completely take place, so even after the pipeline passes, you may still have an instance where the origial link AND the new link both still work.
Keep in mind that if there are links throughout the handbook that link to the old page, you will need to update those links so people don't receive a 400 error when clicking on those links.
You may also request a redirect. That process is outlined here.
This video covers:
This video covers:
Note: Flowcharts are universally used to outline the steps of a processes in sequential order. Every shape or symbol has its own function in a flowchart.
This video covers:
This video covers:
This video covers:
Every GitLab team member has an entry in team_members/person. There are step by step instructions on how to update the individual YAMLs in the Edit this website locally handbook page
When a new manager joins a team, updates are needed in three places:
reports_to
to include the new manager slugstages.yml
to indicate the new manager for the team (if part of engineering/product)Some tips may require terminal shell access on macOS/Linux. Ensure that your environment is working and that you have cloned the www-gitlab-com project for example.
git clone https://gitlab.com/gitlab-com/www-gitlab-com.git
Sync it. Ensure that you stash away local changed not yet committed.
cd www-gitlab-com
git stash
git checkout master
git pull
On macOS it is advised to use Homebrew and install the GNU tools. See this blogpost for a macOS setup.
brew install gnu-sed
One of the shell tools provided with macOS/Linux GNU is find
. Open a terminal an run the following command in the main directory of the www-gitlab-com
repository to get a list of all *.md
files. This matches .md
as suffix.
find . -type f -name '*.md'
Instead of the .
you can also use a directory in the current path.
find source/handbook -type f -name '*.md'
The type f
specifies files, d
matches for directories. When not specified, all files and directories are taken into account.
You can replace -name
with -regex
to do more sensitive matching, for example to match all .md
and .md.erb
files.
find . -type f -regex '.*\.md[.erb]*'
This can be useful to check whether a blog post was merged to master:
git checkout master
git pull
find . -type f -name '*blogpost-filename*'
This comes in handy when you want to print all matches with a prefix, or perform additional replace actions. The main principle is to follow the matching rules explained above, and add the -exec
parameter.
The exec
action should start a shell and execute a command in there. sh -c '' \;
takes care of this for every file that matches. Imagine this as a loop of sequential steps to perform the action. The last missing bit is accessing the file in the current loop iteration. This is done via the {}
marker inside the echo
example printing the output.
Run the command in a terminal to see how it works:
find source/handbook/marketing -type f -name '*.md' -exec sh -c 'echo "Matched {}"' \;
The GNU sed
shell command is useful to replace a defined string in a file. The -i
flag specifies to do that inline in the same file. The g
flag defines a global match, replacing all pattern matches.
sed -i 's/<searchtext>/<replacementtext>/g' file.md
On macOS, ensure that the gnu-sed
package is installed, and run gsed
(instead of sed
).
gsed -i 's/<searchtext>/<replacementtext>/g' file.md
With using the /
separator, it is necessary to escape all /
characters in the string. You can avoid this by choosing another separator, for example ,
:
gsed -i 's,<searchtext>,<replacementtext>,g' file.md
Sometimes a project, URL target or Slack channel is being renamed. You can easily search and edit with the Web IDE on GitLab.com but for other files there is a quick and automated way required.
This method combines the find, exec and sed tips explained above. The exec
action is now to use sed to perform an inline replacement of a pattern/string.
The following example is used in this MR for updating the Corporate Marketing project URL in all files.
git checkout master
git pull origin master
git checkout -b handbook/corp-mktg-project-url
find source/handbook -type f -exec sh -c 'gsed -i "s,https://gitlab.com/gitlab-com/marketing/corporate-marketing,https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing,g" "{}"' \;
git status
git diff
git commit -av -m "Handbook: Update corporate marketing project URL"
git push -u origin handbook/corp-mktg-project-url
<open URL in browser for MR>
To cut it down:
source/handbook
directory. The URL might be found in other files too.exec
runs a sed/gsed
actionhttps://gitlab.com/gitlab-com/marketing/corporate-marketing
with https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing
git status
and git diff
before committing themYou can also do bulk find and replace operations using Visual Studio Code along with the GitLab Workflow extension for VS Code. The following steps were used in this MR for updating sub-value
to operating principle
.
On macOS this can be a fairly seamless experience if you clone the project (www-gitlab-com
for the Handbook) using SSH and then use 1Password for SSH & Git.
Once you've configured and installed Visual Studio Code
and logged into the GitLab Workflow extension for VS Code
open the www-gitlab-com
directory where you've synced the repo.
Create a new branch by:
master
in the bottom barCreate new branch
You can then use the Search
functionality (⌘⇧F
) to find all files matching your desired search. Searching in Visual Studio Code
allows matching case, matching whole word, or using Regular Expressions. If you click on the ellipsis (…
) you also have the option to include or exclude files by pattern matching on the path (uses commas to delimit multiple includes/excludes).
You can do a Replace All
across all files with the matching search term directly in the Search
functionality:
Search
field or enter ⌘⇧H
Search
termReplace
termReplace All
button next to the Replace
field or enter ⌥⌘Enter
Once you've made your edits use the Source Control
(⌃⇧G
) functionality to:
+
sign for each file, or the +
sign for the entire commit⌘Enter
You can use the GitLab Workflow
extension to manage the Merge Request
(MR) once the branch has been pushed and MR created.