ModelsAgentsInfrastructurePricingDocsBlogSecurity

Connect GitHub to your Studios

Connect your GitHub account once, and git and the GitHub CLI (gh) work with your repositories in every Studio you start, with nothing to set up in the Studio. The connection uses the Lightning AI GitHub App, which can access only the repositories that you, or an admin of your GitHub organization, choose. For anything the app isn't allowed to do, such as pushing a change to a workflow file, you log in with your own GitHub account for a few hours with gh auth login.

To learn how the connection works and how it's kept secure, see GitHub access in Studios.

Before you begin

  • A GitHub account on github.com, or on your organization's GitHub Enterprise instance once an organization admin has added it.
  • To install the app on a GitHub organization, you need to be an admin of that organization. Otherwise you can ask an admin to install it, as described below.

Connect your GitHub account

  1. Open your profile menu and select Global settings, then Integrations.
  2. In the GitHub section, select Connect GitHub. If your organization has added GitHub Enterprise, a menu opens: choose GitHub.com, or your organization's GitHub Enterprise hostname.
  3. On GitHub, authorize the Lightning AI app. You return to Integrations, which shows Connected as and your GitHub username.

You can connect both github.com and your organization's GitHub Enterprise instance. Each connection has its own box on the Integrations page.

Choose the repositories the app can access

The app can access only the accounts and organizations it's installed on, and only the repositories chosen for each one. You choose them on GitHub.

  1. In your connection's box on Integrations, select Install or configure the app on GitHub.
  2. On GitHub, pick your personal account or an organization, then choose all repositories or only the ones you select.
  3. Return to Integrations. Each account the app is installed on has a row with a Connected label and a Configure link to change its repositories on GitHub.

If you aren't an admin of the GitHub organization, GitHub lets you request the installation instead. The request shows on Integrations with a Pending label until an admin of that organization approves it.

Changes you make on GitHub normally reach Integrations on their own. To fetch them straight away, select Refresh.

Use git and gh in a Studio

With GitHub connected, git and gh in a Studio are already signed in to GitHub as you, for github.com and for your organization's GitHub Enterprise host. You don't need an SSH key, a personal access token or gh auth login.

In a Studio terminal, clone and push as usual:

git clone https://github.com/OWNER/REPO.git

Or, with gh:

gh repo clone OWNER/REPO

Replace OWNER/REPO with a repository the app can access. A public repository clones even when the app can't access it, so test with a private one.

Each Studio also sets up the following when it starts:

  • SSH remotes such as git@github.com:OWNER/REPO.git work without an SSH key in the Studio. If GitHub isn't connected for the host, SSH remotes use your own keys.
  • Your git user.name and user.email are set from your GitHub account. If your GitHub profile has no name, user.name is your GitHub username.

In a Studio in an organization that has added GitHub Enterprise, gh run outside a repository talks to the organization's GitHub Enterprise host. Inside a repository, it talks to the host of the repository's remote.

If you disconnect GitHub on Integrations, Studios that are already running will stop being able to access GitHub within ten minutes.

What the app can and can't do

The app has a deliberately small set of permissions: enough for everyday development, and no more, so that a Studio holds as little of your GitHub access as it can. With your GitHub connection, git and gh can:

  • Clone, pull and push, including branches and tags.
  • Open, review, comment on and merge pull requests.
  • Read, open and comment on issues.
  • Read check results, commit statuses and GitHub Actions runs, including their logs.
  • Read the members and teams of a GitHub organization.
  • Read your email address, for your commits.

The app can't create or change files in .github/workflows, re-run or start workflows, write commit statuses, or manage deployments, repository secrets and variables, security alerts, Discussions or Projects. For any of these, use your own login.

Use your own GitHub login for more permission

gh auth login in a Studio logs you in with your own GitHub account for a time you choose, eight hours at most. Until then, git and gh in that Studio use your full user permissions instead of the app's limited permissions. This works whether or not GitHub is connected, and for any GitHub host.

  1. In a Studio terminal, run:

    gh auth login --for 2h

    --for takes a duration such as 30m or 2h. Without it, the login lasts eight hours, which is also the most it can last.

    To push a change to a workflow file, add --scopes workflow. To log in to a host other than the default, add --hostname and the host, for example --hostname ghe.example.com. The default host is github.com, or your organization's GitHub Enterprise host if it has added one.

  2. Complete the login in your browser, as gh asks. The terminal then says which account you're logged in as and when the login ends.

The login ends at that time, when you run gh auth logout, or when the Studio stops, whichever comes first. git and gh then go back to your GitHub connection, or to no GitHub access if GitHub isn't connected. A login doesn't survive a restart of the Studio.

To see which login git and gh are using, and how long your own login has left, run:

gh auth status

To add scopes to an active login without changing when it ends, run gh auth refresh --scopes workflow.

gh auth login --with-token, gh auth switch and gh auth setup-git aren't available in a Studio. For a login that lasts longer than eight hours, use a personal access token instead.

Use a personal access token

A token you set yourself always wins over your GitHub connection and over a gh auth login, for both git and gh. Set it in one of these environment variables:

  • GH_TOKEN, or GITHUB_TOKEN, for github.com and for GitHub Enterprise Cloud hosts that end in ghe.com.
  • GH_ENTERPRISE_TOKEN, or GITHUB_ENTERPRISE_TOKEN, for a GitHub Enterprise Server host.

To have the token in every Studio you create, add it as a user secret with one of these names.

Give a custom-image job access to GitHub

Jobs that run a custom Docker image don't use your GitHub connection. Create a fine-grained personal access token on GitHub that reaches only the repositories the job needs, with only the permissions it needs, and store it as a secret for the job to use.

Use GitLab in a Studio

Lightning AI doesn't connect to GitLab for you. Create a personal access token on GitLab, add it as a user secret, and run glab auth login in the Studio.

Add GitHub Enterprise for your organization

An organization admin adds a GitHub Enterprise Server, or a GitHub Enterprise Cloud tenant on ghe.com, once for the whole Lightning AI organization. Members then connect their own accounts to it from Integrations. A GitHub organization on github.com needs nothing here: its members install the app as described above.

Lightning AI registers its GitHub App on your instance for you, so nothing is copied by hand.

  1. In your organization's settings, open Integrations.
  2. In the GitHub Enterprise section, select Add GitHub Enterprise.
  3. In Hostname, enter the host of your instance, such as ghe.example.com, without https:// or a path.
  4. In GitHub organization, enter the organization on your instance that will own the app.
  5. Leave Dial hostname empty, unless Lightning AI can't reach your instance directly. See Network access.
  6. Select Continue to and your hostname. On your instance, confirm the app's name and create the app. GitHub App names are unique on an instance, so change the name there if it's taken.

You return to Lightning AI, and the instance is listed in the GitHub Enterprise section with a link to the app. Members can now connect to it, and install the app on organizations on your instance as described above.

To remove the instance, select Delete. Every member's connection to it is removed, and their Studios stop signing in to it. The app stays registered on your instance.

Network access

Lightning AI's servers need to reach your instance's API when you add the instance, when a member connects, and from then on to keep each member's connection working. If your instance isn't reachable from the public internet, set Dial hostname to a public front for it. Lightning AI then connects to that host instead, while browsers still use your hostname. The front has to serve your instance's TLS certificate.

Studios clone, push and run gh against your instance directly. To give Studios access to an instance that isn't publicly reachable, run them on your own cloud account with network access to the instance.

Notes

  • Everyone working in one of your Studios, including collaborators on a shared Studio, uses your GitHub connection there, and your own login while a gh auth login is active. What they push is pushed as you.
  • It works both ways. If you run gh auth login in someone else's Studio, everyone working in it acts on GitHub as you, with your full user permissions, until the login ends.
  • Any code that runs in the Studio can use that access too. Before you share a Studio or run code you don't trust, check which repositories the app can access.

Troubleshooting

"Repository not found" or "Permission to OWNER/REPO.git denied"

The app can't access the repository. On Integrations, find the account that owns the repository in your connection's box:

  • If it isn't listed, or the repository isn't one of the selected ones, select Install or configure the app on GitHub and add it.
  • If it's marked Suspended, the row says who can restore it. Ask them to.
  • If it's marked Pending, an admin of that organization still has to approve the installation.

Then run the command again.

"refusing to allow a GitHub App to create or update workflow"

The app can't change files in .github/workflows. Log in with your own account for long enough to push, then push again:

gh auth login --scopes workflow --for 1h

git prints a line that starts with `lightning:`

The Studio has no GitHub access for that host, and the line says why. Usually GitHub isn't connected, or the connection was revoked. Connect it on Integrations, select Connect again on a revoked connection, or run gh auth login.

See also

Was this page helpful?

What went wrong?

↑↓ Navigate↵ Open⌘↵ New tabesc Close