[docs] GitHub proxy admin guide and tsh reference

docs/pages/admin-guides/management/guides/github-integration.mdx

@@ -0,0 +1,144 @@
+---
+title: GitHub Integration
+description:  How to use Teleport's short-lived SSH certificates with the GitHub Certificate Authority.
+---
+
+Teleport can proxy Git commands and use short-lived SSH certificate to
+authenticate GitHub organizations that trust Teleport's certificate authorities.
+
+In this guide, you will:
+- Create a GitHub OAuth application for Teleport to obtain user's GitHub
+  identities.
+- Configure SSH certificate authorities for your GitHub organizations.
+- Create Teleport resources for the GitHub integration.
+- Run Git commands through Teleport
+
+## How it works
+
+GitHub enables organizations to configure a list of SSH Certificate Authorities
+(CAs) for authentication. This feature allows access to the organization's
+repositories using short-lived SSH certificates signed by an approved
+Certificate Authority (CA), such as a Teleport CA. Additionally, organizations
+can enforce stricter security by requiring these signed SSH certificates for
+access, effectively disabling the use of personal SSH keys and access tokens.
+
+Teleport users can configure their Git repositories once to proxy through
+Teleport. After setup, Git commands automatically route through Teleport's
+backend, which impersonates their GitHub identity and uses short-lived SSH
+certificates signed by Teleport's CA for authentication with GitHub.
+
+To retrieve a user's GitHub identity, `tsh` initiates the GitHub OAuth flow by
+opening a browser window for the user to log in with their GitHub credentials.
+
+![GitHub SSH certificate authorities](../../../../img/management/how-it-works-github-proxy.svg)
+
+Note that Teleport proxies Git commands through SSH but the users should
+continue to access github.com regularly through their browsers.
+
+## Prerequisites
+
+- Teleport Enterprise or Teleport Enterprise Cloud cluster version 17.2 or higher.
+- Access to GitHub Enterprise and permissions to modify GitHub's SSH aertificate
+  authorities and configure OAuth applications.
+- (!docs/pages/includes/tctl.mdx!)
+- Git locally installed
+
+## Step 1/4. Configure a GitHub OAuth application
+
+The GitHub integration requires a GitHub OAuth application to obtain users'
+GitHub identities. You can skip this step if the Teleport users use GitHub SSO
+to sign in Teleport.
+
+Go to "OAuth Apps" under "Developer Settings" of your organization's settings.
+Click on "New OAuth App".
+
+Fill in the details. Use the following for "Authentication callback URL":
+```
+https://<Var name="teleport-proxy-address"/>/v1/webapi/github/
+```
+
+Once the OAuth application is created, create a client secret and remember the
+client ID and the secret for the next step:
+
+![A GitHub Oauth App, highlighting Client ID and secret](../../../../img/sso/github-app-vars.png)
+
+## Step 2/4. Create a GitHub integration and export the CAs
+
+Now create a yaml file that represents the Github integration:
+```yaml
+# github_integration.yaml
+kind: integration
+sub_kind: github
+version: v1
+metadata:
+  name: github-<Var name="my-github-org"/>
+spec:
+  github:
+    organization: <Var name="my-github-org"/>
+  credentials:
+    id_secret:
+      id: <Var name="oauth-app-client-id"/>
+      secret: <Var name="oauth-app-client-secret"/>
+```
+Replace `my-github-org` with the organization name, and replace
+`oauth-app-client-id` and `oauth-app-client-secret` with values from the
+previous step.
+
+To create the resource with `tctl`, run:
+```bash
+tctl create -f github_integration.yaml
+```
+
+Once the integration resource is created, export the CA to be used for GitHub:
+```bash
+tctl auth export --type github --integration github-<Var name="my-github-org"/>
+```
+
+Now go to the "Authentication Security" page of your GitHub organization. Click
+on "New CA" under the "SSH certificate authorities" section, and copy-paste the CA
+exported from the above `tctl auth export` command.
+
+![GitHub SSH certificate authorities](../../../../img/management/github-new-ca.png)
+
+## Step 3/4. Configure access
+
+User access is granted through `git_server` resources. The `git_server`
+references the integration created in the previous step:
+```yaml
+# git_server.yaml
+kind: git_server
+sub_kind: github
+version: v2
+spec:
+  github:
+    integration: github-<Var name="my-github-org"/>
+    organization: <Var name="my-github-org"/>
+```
+
+To create the resource with `tctl`, run:
+```bash
+tctl create -f git_server.yaml
+```
+
+The user role must have `github_permissions` configured to allow access to your
+GitHub organization. For example:
+```yaml
+# role_with_github_permissions.yaml
+kind: role
+metadata:
+  name: github-<Var name="my-github-org"/>
+spec:
+  allow:
+    github_permissions:
+    - orgs:
+      - <Var name="my-github-org"/>
+version: v7
+```
+
+You can either create a new role as shown above or add github_permissions to an
+existing role. Ensure the role is assigned to the appropriate Teleport users who
+will access Git repositories through Teleport.
+
+## Step 4/4. Connect
+
+(!docs/pages/connect-your-client/includes/tsh-git.mdx!)

docs/pages/connect-your-client/includes/tsh-git.mdx

@@ -0,0 +1,43 @@
+Use `tsh git ls` to view a list of GitHub organizations you have access to:
+```code
+$ tsh git ls
+Type   Organization  Username URL
+------ ------------- -------- -------------------------
+GitHub my-org        my-name  https://github.com/my-org
+```
+
+Teleport requires your GitHub identity to impersonate you. If you haven't
+provided it yet, run the following command:
+```code
+$ tsh git login --github-org my-org
+  If browser window does not open automatically, open it by clicking on the link:
+   http://127.0.0.1:55555/some-id
+  Your GitHub username is my-name.
+```
+
+This command opens a browser, prompting you to authenticate with GitHub via the
+OAuth app:
+![GitHub SSO authorization view](../../../img/github-sso-auth-screen.jpg)
+
+To clone a repository from your GitHub organization, find the SSH clone URL and
+run:
+```code
+$ tsh git clone git@github.com:my-org/my-repo.git
+Cloning into 'my-repo'...
+```
+
+To configure an existing Git repository with Teleport, go to the repository and
+run:
+```code
+$ tsh git config update
+The current Git directory is configured with Teleport for GitHub organization "my-org".
+```
+
+Once the repo is cloned or configured, you can use `git` commands as normal:
+```
+$ cd my-repo
+$ git fetch
+```
+
+Note that the OAuth app authentication flow and Git repository configuration are
+one-time setups. Once completed, you won’t need to repeat them.

docs/pages/connect-your-client/tsh.mdx

@@ -771,6 +771,10 @@ $ tsh status
   Extensions:         permit-X11-forwarding
 ```
 
+## Proxying Git commands
+
+(!docs/pages/connect-your-client/includes/tsh-git.mdx!)
+
 ## Custom aliases and defaults
 
 You can configure `tsh` to define aliases, custom commands and command-specific flag defaults. Using aliases, you can run frequently used `tsh` commands more easily.

docs/pages/includes/role-spec.mdx

@@ -476,6 +476,12 @@ spec:
         # 'foo.example.com'.
         dns_sans: ["foo.svc.example.com"]
 
+    # GitHub-related permissions used for proxying Git commands.
+    github_permissions:
+      # List of GitHub organizations the user has access to.
+    - orgs:
+      - my-org
+
     # rules allow a user holding this role to modify other resources
     # matching the expressions below
     # supported resources:
@@ -511,6 +517,7 @@ spec:
     # kube_cluster          - Kubernetes cluster resource
     # token                 - provisioning token resource
     # cert_authority        - certificate authority resource
+    # git_server            - Git server resource
     #
     # cluster_name              - resource that contains the cluster name.
     # cluster_config            - resource that holds cluster level config