This document acts a reference for GitLab CI and Machine ID. You will find links to in-depth guides as well as a full description of the configuration options available when using the GitLab join method.
You can read step-by-step guides on using Machine ID and GitHub Actions:
- Using Machine ID with GitLab: How to use Machine ID to SSH into Teleport nodes from GitLab CI.
GitLab join token
A GitLab join token contains allow rules that describe which pipelines can use that token in order to join the Teleport cluster. A rule can contain multiple fields, and any pipeline that matches all of the fields within a single rule is granted access.
The following constraints exist:
sub: a string uniquely identifying the CI run's source. It follows the following format:
kind: token version: v2 metadata: # name identifies the token. When configuring a bot or node to join using this # token, this name should be specified. name: gitlab-demo spec: # The Bot role indicates that this token grants access to a bot user, rather # than allowing a node to join. roles: [Bot] # join_method for GitLab joining will always be "gitlab". join_method: gitlab # bot_name specifies the name of the bot that this token will grant access to # when it is used. bot_name: gitlab-demo gitlab: # domain should be the domain of your GitLab instance. If you are using # GitLab's cloud hosted offering, omit this field entirely. domain: gitlab.example.com # allow is an array of rule configurations for what GitLab CI jobs should be # allowed to join. All options configured within one allow entry # must be satisfied for the GitLab CI run to be allowed to join. Where # multiple allow entries are specified, any job which satisfies all of the # options within a single entry will be allowed to join. # # An allow entry must include at least one of: # - project_path # - namespace_path # - sub # This ensures that GitLab CI runs in other GitLab user's projects are not # able to access your Teleport cluster. allow: # project_path restricts joins to jobs that originate within the # specified project. - project_path: my-user/my-project # namespace_path restricts joins to any run within project that exists # within the specified namespace. A namespace will either be a username # or the name of a group. namespace_path: my-user # pipeline_source restricts joins to jobs triggered by certain criteria, # e.g triggered through the web interface. pipeline_source: web # environment restricts joins to jobs that are associated with the # specified environment environment: production # ref_type restricts joins to jobs that were triggered by a specific # type of git reference. Either `branch` or `tag`. ref_type: branch # ref restricts joins to jobs that were triggered by a specific git # reference. Combine this with `ref_type` to create allow rules that # can only be triggered by a specific branch or tag. ref: main # sub is a single string that concatenates the project_path, ref_type # and ref. This can be used to restrict joins using a single string, # whilst also describing a specific project and git ref. # # It is better to use the individual fields, as it is easy to mis-format # the sub string. sub: project_path:my-user/my-project:ref_type:branch:ref:main