Skip to main content
Version: 19.x (unreleased)

Git Platforms Reference

Report an Issue

This page lists the configuration options, resource shapes, and audit events for Git platforms protected by Teleport.

Configuration​

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

Git over HTTPS stores each user's GitHub credentials encrypted with an Auth-layer key, configured in the auth_service section of teleport.yaml:

auth_service:
  user_external_credentials:
    # encryption_mode configures how the Auth encryption key of user external
    # credentials is managed. "" (default) uses the same keystore as the keys
    # defined in "ca_key_params". "software" uses a software key stored in
    # the backend instead, for Auth servers that do not share an HSM or KMS.
    encryption_mode: ""

integration resource​

A GitHub integration stores the OAuth or GitHub App credentials used to act on behalf of users. One integration resource exists per connected GitHub organization.

kind: integration
sub_kind: github
version: v1
metadata:
  name: github-doc-example-org
spec:
  github:
    # The GitHub organization name.
    organization: doc-example-org
    # The full callback URL for the GitHub OAuth flow, including the proxy's
    # public address and web port.
    oauth_callback_url: https://teleport.example.com:443/web/github/integration/callback
    # Which protocols the organization allows via Teleport: "ssh", "https", or both
    allow_protocols: ["https"]

  # Only settable when creating or updating the resource (e.g. tctl create/edit)
  credentials:
    # The client ID and secret of the OAuth app (SSH-only integrations) or
    # GitHub App (HTTPS integrations).
    id_secret:
      id: oauth-app-or-github-app-client-id
      secret: oauth-app-or-github-app-client-secret

Set oauth-app-or-github-app-client-id and oauth-app-or-github-app-client-secret to the client ID and secret of your GitHub OAuth app (SSH-only integrations) or GitHub App (HTTPS integrations). Replace teleport.example.com:443 with the host and web port of your Teleport Proxy Service.

git_server resource​

A git_server resource grants users access to a GitHub organization through an integration. The git_server's allow_protocols must match the integration's.

kind: git_server
sub_kind: github
version: v2
metadata:
  name: github-doc-example-org
spec:
  github:
    # Name of the integration resource this git_server references.
    integration: github-doc-example-org
    # The GitHub organization name. Must match integration's organization.
    organization: doc-example-org
    # Must match the integration's allow_protocols.
    allow_protocols: ["https"]

Audit events​

See the Git audit event reference for the events Teleport records for Git platforms.