This document acts a reference for GitHub Actions and Machine ID. You will find links to in-depth guides on using GitHub Actions and a full explanation of the configuration options available when using the GitHub join method.
You can read step-by-step guides on using Machine ID and GitHub Actions:
- Using Machine ID with GitHub Actions: How to use Machine ID to SSH into Teleport nodes from GitHub Actions.
- Using Machine ID with GitHub Actions and Kubernetes: How to use Machine ID to access Kubernetes clusters from GitHub Actions.
GitHub join token
token resource sets out rules for what is allowed to join a Teleport
cluster. Joining clients must specify which
token they want to use, and then
information included in their join request is compared to the rules contained
within the token by the Auth Server to determine whether or not they should be
The following snippet shows all available options in the
token resource when
used for GitHub joining with Machine ID:
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: github-token spec: # For Machine ID and GitHub joining, roles will always be `Bot` and # join_method will always be `github`. roles: [Bot] join_method: github # bot_name specifies the name of the bot that this token will grant access to # when it is used. bot_name: github-demo github: # enterprise_server_host allows joining from GitHub Actions workflows in a # GitHub Enterprise Server instance. For normal situations, where you are # using github.com, this option should be omitted. If you are using GHES, # this value should be configured to the hostname of your GHES instance. enterprise_server_host: ghes.example.com # allow is an array of rule configurations for what GitHub Actions workflows # should be allowed to join. All options configured within one allow entry # must be satisfied for the GitHub Actions run to be allowed to join. Where # multiple allow entries are specified, any run which satisfies all of the # options within a single entry will be allowed to join. # # An allow entry must include at least one of: # - repository # - repository_owner # - sub allow: - # repository is a fully qualified (e.g. including the owner) name of a # GitHub repository. repository: gravitational/teleport # repository_owner is the name of an organization or user that a # repository belongs to. repository_owner: gravitational # workflow is the exact name of a workflow as configured in the GitHub # Action workflow YAML file. workflow: my-workflow # environment is the environment associated with the GitHub Actions run. # If no environment is configured for the GitHub Actions run, this will # be empty. environment: production # actor is the GitHub username that caused the GitHub Actions run, # whether by committing or by directly despatching the workflow. actor: octocat # ref is the git ref that triggered the action run. ref: ref/heads/main # ref_type is the type of the git ref that triggered the action run. ref_type: branch # sub is a concatenated string of various attributes of the workflow # run. GitHub explains the format of this string at: # https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims sub: repo:gravitational/example-repo:environment:production
GitHub Actions helpers
We offer a series of off-the-shelf GitHub Actions to use in your workflows when utilizing Teleport Machine ID and GitHub Actions.
More information about these individual actions can be found in their GitHub repositories:
If you experience problems when using these actions, please raise an issue in their source repository: https://github.com/teleport-actions/root.