GitLab Runner beginner tutorial: Create and run your first runner
Problem to solve
This tutorial provides instructions about how to create and run a runner for the first time.
The goal for this tutorial is to lay the groundwork for beginners to become familiar with the basic runner concepts and configuration requirements before they move on to more complex runner configurations.
Ideally after merge, this tutorial will be highlighted as being Good for beginners on the Build your application tutorial page, in the Configure GitLab Runner
section.
Basic concepts users should understand after the tutorial
- Runner tags.
- Authentication tokens.
- Creating and registering runners.
- Executors (this tutorial will use
shell
as it has the most simple configuration). - How
config.toml
and.gitlab-ci.yml
are used when configuring the runner.
Proposal
Create a tutorial that describes a basic yet commonly used configuration scenario.
Steps to include (very rough outline, WIP):
- Creating a project runner in the UI. Should include:
- Basic configurations:
- What tags to use based on the configuration requirements.
- Basic configurations:
- Registering the runner. Should include:
- Defining the type of executor and executor configuration (this should be
shell
as it's the most straightforward configuration)
- Defining the type of executor and executor configuration (this should be
- Other configurations needed in
.gitlab-ci.yml
. (?) - Starting the runner from the command line (and other basic commands).
- Viewing the runner in the UI.
Config file examples to include:
-
config.toml
after the runner has been created and registered. .gitlab-ci.yml
Use case example
The tutorial might benefit from a simple use case to ground it in the real world. This would make explanation of tags and gitlab.ci.yml
more relatable.
Who can address the issue
Technical writer for grouprunner with input from developers.
Other links/references
FY24Q2 TW KR: Write tutorials to provide how-to... (technical-writing#790 - closed)