Source control
Unlike local runs, cloud environments do not already have your project checked out. To make repositories available for the cloud environments, configure integration with a supported VCS provider: GitHub, GitLab, or a self-hosted GitHub Enterprise Server or GitLab Self-Managed instance.
Repository access is based on a connection app in your VCS provider, and the details differ from provider to provider – see How repository access works.
You can start the connection flow from the web version of JetBrains Air. In JetBrains Air and AI Assistant in IntelliJ-based IDEs, repository authorization is started from the cloud task flow.
Connect repositories to Air
Make sure the following prerequisites are met:
You have access to the repository you want to work on in your VCS provider.
For GitHub organization repositories – the JetBrains Air connection app is installed in GitHub for the organization that owns the repository. A user with administrative permissions in that organization does this once – see Set up organization repository access.
For repositories on a self-hosted GitHub Enterprise Server – the instance is registered for your organization in JetBrains Central Console, and the generated app is installed on the server. An organization administrator does this once – see Set up organization repository access.
For repositories on a self-hosted GitLab Self-Managed – the instance is registered for your organization in JetBrains Central Console. An organization administrator does this once – see Set up organization repository access.
For personal repositories – no extra setup is needed. You authorize the app for your own account as part of the connection flow, and on GitHub you install it for your account at the same time.
Connect repositories
Start the connection flow.
From the web version of JetBrains Air:
In the web version of JetBrains Air, go to , find your VCS provider, and click Connect.
From JetBrains Air or AI Assistant:
Start creating a task and select a cloud run environment. See how to do it in JetBrains Air and in AI Assistant. The task flow prompts you to connect the provider when access is needed.
If the JetBrains Air connection app isn't authorized yet, click Authorize and complete the provider's authorization flow.
Authorizing lets the app act on your behalf in the provider, for example, to read code and open pull requests. It doesn't widen what you can reach – you never gain access to repositories you can't already access in the provider.
After the connection is established, the connected provider appears in the web version of JetBrains Air under , showing the connected account and the organizations available through that connection.
Finish the flow. What happens next depends on your VCS provider.
GitHub and GitHub Enterprise Server – authorization grants access to your personal repositories but not to organization repositories.
If the task still can't run, read access to the target repository is required. Click Manage to open GitHub and grant the app access to the repository, or request it if you aren't entitled to grant it yourself. See Manage repository access.
Organization owners are notified about the request, but repository admins aren't. If the repository is administered by a repository admin, contact them directly.
GitLab and GitLab Self-Managed – authorizing completes the connection. Cloud tasks can use every repository you can access in GitLab, with no extra step.
A cloud task runs against one repository. If the agent also needs code from another repository, for example shared skills or configuration, clone it from the environment's startup script – see Clone additional repositories.
How repository access works
How JetBrains Air accesses your repositories depends on the provider. GitHub and GitHub Enterprise Server are the only providers with an installation step: someone installs a connection app into an account, and that installation carries its own list of repositories it can access. Every other provider uses a plain OAuth authorization that is scoped to you, with nothing to install.
- Whose access the agent uses
When a cloud task reads your code or opens a pull request, it acts within your own access rights and never sees repositories you can't already access in the VCS provider. Connecting JetBrains Air doesn't widen what you can reach – it only lets JetBrains Air act on the repositories you already have access to.
To the VCS provider, access goes through the JetBrains Air app with your authenticated user as the principal, so the provider's own permissions gate every action.
Within JetBrains Air, the cloud task operates under your user or service account.
GitHub
On GitHub, repository access goes through the JetBrains Air connection app, published as JetBrains Air in the GitHub Marketplace.
- The app is installed per account, not per repository
The JetBrains Air connection app is installed into a GitHub account – a personal account or an organization – not into individual repositories. You install it once per account, then choose which repositories that installation can access: all repositories or only selected ones. You can change this selection at any time (see Manage repository access).
Connecting GitHub involves two distinct actions:
Installing the app – an administrator installs the JetBrains Air connection app into a GitHub account – a personal account or an organization – and chooses which repositories the app can access. This is what makes those repositories available to JetBrains Air.
Authorizing the app – each user authorizes the JetBrains Air connection app to act on their behalf, for example, to view issues and create pull requests. This is an OAuth flow.
Sometimes one person performs both actions. For example, when you connect your own personal account, you both install the app for that account and authorize it to act on your behalf. For an organization, an administrator usually installs the app, and each user then authorizes it for themselves.
- Who can grant the app access to a repository
A user can grant app access in these cases:
Personal repositories – if the app is installed in the user's personal account, the user can grant access to their personal repositories.
Organization repositories – organization owners can grant the app access to organization repositories.
Repository admins – repository administrators can grant access to repositories they administer, if the organization allows repository administrators to install GitHub apps.
Users with only normal read or write access cannot directly grant the app access to a repository. On GitHub, such repositories can appear with a Request badge instead.
If you aren't an owner or repository admin, you can't install the app yourself. When you start the connection flow, GitHub sends an installation request to your organization's owners, similar to requesting any other third-party GitHub app. After an owner approves and installs the app, you can authorize it for yourself and access the repositories you're entitled to.
But repository admins aren't notified about requests for the repositories they administer. If the repository you need is administered by a repository admin rather than an organization owner, contact them directly.
- How to make a repository appear in JetBrains Air
Installing the app for an organization does not mean that every repository in that organization will appear for every user in JetBrains Air.
A repository appears in JetBrains Air only if both of the following are true:
the app installation has access to that repository
the user has explicit repository access in GitHub
Repository type
When it appears in JetBrains Air
Personal repository
The app is installed in the personal account and has access to the repository.
Organization public repository
The organization installation has access to the repository.
Organization private repository
The organization installation has access to the repository, and the user has explicit repository access in GitHub.
Organization internal repository
The organization installation has access to the repository, and the user has explicit repository access in GitHub. Organization membership alone is not enough.
Internal repositories need special attention. A user may be able to open an internal repository directly in GitHub because they belong to the organization, but the same repository still may not appear in JetBrains Air.
For internal repositories, the usual fix is to grant the user explicit repository access, for example through a team or a direct collaborator role.
GitHub Enterprise Server
A self-hosted GitHub Enterprise Server instance isn't available to JetBrains Air until an organization administrator registers it in JetBrains Central Console. Registration creates a GitHub App on your own server, so the instance gets its own connection app instead of using the JetBrains Air app from the GitHub Marketplace.
From there, repository access follows the same rules as GitHub: the app is installed per account, each user authorizes it for themselves, and a repository appears in JetBrains Air only if both the installation and the user can reach it.
Connecting a self-hosted instance doesn't replace GitHub cloud – you can use both at the same time. If your organization registers several instances, each one appears as a separate provider in .
GitLab
GitLab has no installation step. You authorize JetBrains Air once through OAuth, and the authorization is scoped to you: cloud tasks can use any repository you can access in GitLab.
The authorization requests these GitLab scopes:
api– acting on your behalf through the GitLab API, for example, to open a merge requestread_repository– cloning the repository into the cloud environmentwrite_repository– pushing the task branch back to GitLab
To change which repositories a cloud task can reach, change your own access in GitLab.
GitLab Self-Managed
A self-hosted GitLab Self-Managed instance isn't available to JetBrains Air until an organization administrator registers it in JetBrains Central Console. Registration connects an OAuth application from your own server, so JetBrains Air authenticates against that server instead of GitLab.com.
From there, access works exactly like GitLab: nothing is installed, you authorize JetBrains Air for yourself, and cloud tasks can use any repository you can access on that server. The organizations shown for the connection are your GitLab namespaces.
Connecting a self-hosted instance doesn't replace GitLab.com – you can use both at the same time. If your organization registers several instances, each one appears as a separate provider in .
Set up organization repository access
Setting up repository access is one part of setting up JetBrains Air for an organization. For the other steps, see Set up Air for your organization.
What you set up depends on the provider. GitHub needs the connection app installed for the organization that owns the repositories, and a self-hosted instance has to be registered in JetBrains Central Console first. Cloud GitLab needs nothing – each user authorizes access for themselves.
Until you register a self-hosted instance, developers don't see it in . After that, they can connect it and reach the repositories available to them. To take an instance out of JetBrains Air again, select Discard connection for it on the Hosted VCS page.
GitHub
To make organization repositories available in JetBrains Air, the JetBrains Air connection app must first be installed for that organization in GitHub.
This first step must be done by a user with sufficient administrative permissions in that organization – see Who can grant the app access to a repository.
Grant JetBrains Air access to GitHub organization repositories
In the web version of JetBrains Air, go to .
Find GitHub and click Connect.
In the GitHub flow opened by the web version of JetBrains Air, install the JetBrains Air connection app for the organization.
Grant the app access either to all organization repositories or only to selected repositories.
Only the repositories granted to the app at this stage can later appear in JetBrains Air.
After that, users from that organization can connect GitHub in JetBrains Air and access the repositories that are available to them according to GitHub's access rules.
GitHub Enterprise Server
Register the instance in JetBrains Central Console, install the generated app on your server, and grant it access to the repositories JetBrains Air may use.
The JetBrains Central Console documentation covers the same flow in more detail, including how to create the GitHub App manually, which repository permissions it needs, and the webhook setup that JetBrains Air automations rely on – see GitHub Enterprise Server.
Grant JetBrains Air access to GitHub Enterprise Server repositories
In JetBrains Central Console, go to .
Click Connect VCS and select GitHub Enterprise Server.
On the Automatic tab, enter the URL of your Enterprise Server and the name of the organization on that server that will own the app – not your JetBrains Central Console organization. Then click Connect.
JetBrains Central Console creates the GitHub App on your server for you. To create the app yourself instead, switch to the Manual tab and provide its credentials: the app ID, client ID, client secret, install URL, private key .pem file, and webhook secret.
Click Install app. GitHub opens the app installation page on your server.
Choose whether the app can access all repositories in that organization or only selected ones, then click Install.
Only the repositories granted to the app at this stage can later appear in JetBrains Air.
Back in JetBrains Central Console, click Authorize and complete the authorization on your server.
Authorizing lets the app act on your behalf. It doesn't change which repositories the app can reach.
Check that the instance shows as Connected in JetBrains Central Console. It's now connected in the web version of JetBrains Air too, under .
Registration and installation are one-time steps. Once the app is installed, every other user authorizes the instance for themselves from in the web version of JetBrains Air – see Connect repositories to Air.
GitLab Self-Managed
Register the instance in JetBrains Central Console. Unlike GitHub Enterprise Server, there's nothing to install and no repository selection to make: each developer authorizes the instance for themselves and works with the repositories they can already reach on that server.
The JetBrains Central Console documentation covers the registration in more detail – see GitLab Self-Managed.
Grant JetBrains Air access to GitLab Self-Managed repositories
In JetBrains Central Console, go to .
Click Connect VCS and select GitLab Self-Managed.
On your GitLab server, create an OAuth application.
In JetBrains Central Console, fill in the credentials of that application: the URL of your GitLab server, the application ID, and the secret. Then click Connect.
Click Authorize and complete the authorization on your GitLab server.
Check that the instance shows as Connected in JetBrains Central Console. It's now connected in the web version of JetBrains Air too, under .
Registration is a one-time step. Every other user authorizes the instance for themselves from in the web version of JetBrains Air – see Connect repositories to Air.
Manage repository access
On GitHub and GitHub Enterprise Server, you choose which repositories the connection app can access. You can open repository access management from in the web version of JetBrains Air, or from the Manage button shown in the task flow when a task needs read access to a repository.
Manage repository access
In the web version of JetBrains Air, open .
Find the connected provider and click Manage Access.
Update repository access.
For example, in GitHub you can choose:
All repositories – the app can access all current and future repositories in that account
Only select repositories – the app can access only the repositories you choose
For a personal account, switching to Only select repositories lets you choose which of your repositories the app can access.
For an organization account, the list can also include repositories that are allowed for the app installation but that you cannot grant yourself. On GitHub, such repositories can appear with a Request badge. You can request access to those repositories from this screen. Organization owners are notified about the request, but repository admins aren't, so contact them directly.
Save the changes.
If a repository does not appear in JetBrains Air
If a repository is missing from the repository list in JetBrains Air, check the following:
the provider is connected in JetBrains Air
on GitHub, the app installation has access to that repository
you are connected to the correct personal or organization account
you have the required repository access in the VCS provider
for GitHub internal repositories, you are not relying only on organization membership visibility
for a self-hosted instance, you connected that instance rather than the cloud provider of the same family
for a repository you just created, GitHub's own search index may not include it yet – wait a few minutes and try again
If a self-hosted instance you expect isn't listed under at all, ask an organization administrator to register it in JetBrains Central Console – see GitHub Enterprise Server or GitLab Self-Managed.