Skip to main content

Protect Agentic GitHub Access with Teleport Beams

Report an Issue

Teleport Beams allow you to grant AI agents access to your GitHub repositories with restricted permissions that prevent their nondeterministic access patterns from unintentional changes.

In this guide, you will set up Teleport RBAC to enable an AI agent to securely access a GitHub repository.

How it works​

Teleport Beams are micro VM sandboxes for running agentic workloads, hosted on the Teleport Cloud infrastructure. When a user creates a beam, the Teleport Auth Service creates a delegation session that contains the user and their Teleport roles.

An instance of the tbot daemon on the beam receives the ID of the delegation session and queries the Auth Service to issue a fresh Teleport identity to services that run on the beam. As a result, any agentic workloads running on the beam delegate the originating user's Teleport permissions.

With Teleport RBAC, you can limit the permissions that agentic workloads have to access your GitHub repositories. You can configure your GitHub organization to use a Teleport certificate authority for authenticating users via SSH. Teleport then issues SSH certificates to users and proxies git commands to enforce RBAC. Users who create a beam can run AI agents on the beam to access repositories that belong to Teleport-protected GitHub organizations, as long as the users have permissions to access those organizations as well.

Prerequisites​

  • A Teleport Beams account. Start your free trial.
  • A GitHub organization enrolled with Teleport. This guide assumes that you have followed Proxy Git Commands with Teleport for GitHub. While you may use a demo organization to follow this guide, it is up to you to configure access controls for users in the organization. Once a user authenticates to GitHub via Teleport as a particular GitHub user, they have all of the permissions you assigned to them in GitHub.
  • A role that can access your GitHub organization. You will have created this while setting up Teleport GitHub support. Teleport access controls for GitHub encompass an entire organization, so this will be the same role you will need to assign to your AI agent later in this guide.
  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=email@example.com
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Configure Teleport RBAC​

You can enable an AI agent to access a Teleport-protected GitHub organization on a Teleport beam by configuring a user with access to:

  • create and access a beam
  • access your GitHub organization

By following the Prerequisites of this guide, you will have already created a role that can access your GitHub organization. The preset beam-user role allows a user to create beams.

  1. Create a user with both roles, assigning github-access to the role you created when enrolling your GitHub organization with Teleport and github-user to the name of your new user:

    tctl users add \  --roles=github-access,beam-user github-user

  2. Follow the instructions in your terminal to activate your user.

Step 2/3. Prepare your beam​

Create a beam and start an SSH session with it:

  1. Authenticate to Teleport as the github-user user you created in the last step and enter your credentials:

    tsh login \  --proxy=example.beams.sh \  --user=github-user

  2. Create a beam and access it:

    tsh beams add

This command starts an SSH session with the new beam.

Stay in the beam shell session for the next step.

Step 3/3. Prompt your agent​

Prompt your agent to access your GitHub organization.

  1. Start your LLM CLI. A beam initializes with claude and codex preinstalled.

  2. Enter the following prompt, assigning repo-url to a repository URL within your protected organization:

    Clone repo-url and summarize the last five merged PRs.

  3. Open the Teleport Web UI at example.beams.sh and navigate to Audit on the left sidebar.

You should see an audit event similar to the following:

{
  "code": "TGIT001I",
  "event": "git.command",
  "time": "2026-08-11T14:32:07.000Z",
  "uid": "7699b806-e717-4821-85a5-d2f41acbe373",
  "user": "github-user",
  "service": "git-upload-pack",
  "path": "<my-github-org>/<repo>"
}

The git.command event type indicates the GitHub user responsible for a git command as well as the low-level protocol operation the user executed. In this case, we can see that the user invoked a read operation on the git server, git-upload-pack.