Skip to main content
For operators. This guide is for the person who installs and configures the Oxygen server. End users who want to import a repository just click Import from GitHub in the Workspaces UI — they don’t need to read this.

Overview

In multi-workspace mode, Oxygen uses a GitHub App (not a personal OAuth app) to:
  • Import repositories as workspaces (“Import from GitHub”)
  • Clone repositories on the server when a workspace is created
  • Read and push commits through the built-in IDE Git panel
The same GitHub App handles both user authentication and repository access. This guide walks through creating the app, configuring permissions, and setting the required environment variables.
GitHub App integration is only needed for multi-workspace mode (the default oxy serve). If you run oxy serve --local, the workspace files already exist on disk and no GitHub integration is required.

Step 1: Create the GitHub App

  1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (For an organization app, go to Organization Settings → Developer settings)
  2. Fill in the app details:
  3. Click Create GitHub App.

Step 2: Configure Permissions

After creating the app, go to Permissions & Events and set:

Repository permissions

Organization permissions

Without Organization → Members: Read, only GitHub org owners and admins will be able to connect their account. Regular org members will see “GitHub App not installed” even after the app has been installed on the org. Enable this permission and re-install the app if this happens.
Leave all other permissions at “No access” and save. If you turned the webhook on, open Subscribe to events on the same page and tick Push.

Step 3: Generate a Private Key

  1. Scroll to the Private keys section on the app settings page.
  2. Click Generate a private key.
  3. GitHub downloads a .pem file — keep this safe.
The private key content is the value for GITHUB_APP_PRIVATE_KEY. It should start with -----BEGIN RSA PRIVATE KEY-----.

Step 4: Note Your App Credentials

From the app settings page, collect these values:

Step 5: Set Environment Variables

Set the following on your Oxygen server:
GITHUB_STATE_SECRET must stay the same across server restarts and deploys. If it changes, users in the middle of an OAuth flow will see “Invalid state parameter” and have to start over. Generate it once, store it in your secrets manager, and never rotate it unless you intentionally want to invalidate active sessions.
The GITHUB_APP_PRIVATE_KEY value must include the full PEM block with literal newlines, not \n escape sequences. In a .env file, wrap the value in double quotes and paste the key with actual line breaks.

Formatting the private key in .env

Formatting the private key in Kubernetes secrets

Store the base64 value in your Kubernetes secret and reference it with envFrom or externalSecrets.

Step 6: Install the App

Before users can import repositories, the GitHub App must be installed on the target GitHub organization or user account:
  1. Go to https://github.com/apps/{your-app-slug}
  2. Click Install and select the organization/account
  3. Choose “All repositories” or specific repositories
  4. Click Install
After installation, users can connect their account by clicking Sign in with GitHub in the Workspaces UI.

Step 7: Verify Callback URL Routing

Oxygen derives the OAuth callback URL automatically from the Origin header of the browser request — no hardcoding is needed. However, ensure:
  1. The callback URL in GitHub matches the domain your users access. For example, if users go to https://app.example.com, the callback must be https://app.example.com/github/callback.
  2. Your reverse proxy forwards the Origin header to the Oxygen backend. Most proxies (nginx, Caddy, ALB) do this by default.
  3. OXY_API_URL is set if your backend is at a different URL than the frontend:

How the Connect Flow Works for Users

When a user clicks Import from GitHub in the Workspaces UI, Oxygen walks them through connecting their GitHub account and selecting a repository.

Step 1 — Connect a GitHub account

Oxygen opens a GitHub OAuth popup. The user authorizes the app, and GitHub redirects back with a short-lived code that Oxygen exchanges for an access token. This token is used to discover which GitHub App installations are visible to that user. There are three possible outcomes:

Step 2 — Select a repository

Once an installation (GitHub account or organization) is connected, the user sees the repositories that the GitHub App has access to. They pick one and Oxygen clones it as a new workspace.

Connecting a different account

If a user wants to import from a different GitHub account or organization, they can click Use a different GitHub account in the connect dialog. This opens a fresh OAuth popup and lets them authorize a different account — the newly authorized account replaces the previous one for future imports.
The GitHub App must be installed on any account or organization before its repositories appear in the picker. See Step 6: Install the App above, or ask the org owner to install it.

Security: Who Can Connect an Installation

Connecting a GitHub App installation decides which repositories an organization can read, so Oxygen checks two things every time one is connected — from the picker, or when GitHub sends the user back after installing the app:
  1. The user is an owner or admin of the Oxygen organization. Members can still connect a personal access token, which only they can use.
  2. The user’s connected GitHub account can reach the installation. Oxygen asks GitHub for the installations that account can access (GET /user/installations) and accepts only one of those. For an installation on a personal GitHub account, that account must also be the user’s own connected login. Any other installation ID gets the same answer as one that does not exist, so IDs from other tenants cannot be guessed or injected.
The signed state that carries a flow through GitHub also names the user who started it, and is refused if anyone else completes it.
Reaching an installation is not the same as administering it. GitHub lists an installation to anyone who can access one of its repositories, whether through organization membership or as an outside collaborator on a single repository. So an Oxygen org owner or admin can connect a GitHub organization’s installation that they reach this way. Oxygen can then read every repository that installation covers, which may be more than that person can read on GitHub. Oxygen does not check the user’s role in the GitHub organization. To limit what Oxygen can read, install the app on Only select repositories.

Full Environment Variable Reference


Troubleshooting

“GitHub App not installed” — but the app IS installed The most common cause: the Organization → Members: Read permission is not enabled on the GitHub App. GET /user/installations only returns installations the OAuth user can see. Without Members: Read, only org owners and admins are included; regular members get an empty list, which Oxygen reports as not_installed. Fix:
  1. Go to your GitHub App settings → Permissions & Events → Organization permissions
  2. Set Members to Read-only and save
  3. GitHub will ask you to re-approve the updated permissions — click Accept
  4. Try connecting again
“GitHub callback redirects to localhost” The redirect_uri is derived from the Origin header. Check that your proxy is forwarding the Origin header and that the correct callback URL is registered in the GitHub App settings. “GitHub App ID not configured in environment” GITHUB_APP_ID is not set or not being loaded. Verify your .env file is loaded at server startup or that the environment variable is injected by your deployment platform. “Invalid state parameter” The HMAC verification on the OAuth state failed. This usually means GITHUB_STATE_SECRET changed between when the user started the OAuth flow and when GitHub redirected back. Ensure the secret is consistent across server restarts (don’t regenerate it on every deploy). “Connect your GitHub account to choose one of its installations” The user has no GitHub account connected, or GitHub no longer accepts its stored authorization, so Oxygen cannot confirm the installation is theirs. The user should reconnect their GitHub account and choose the installation again. “Via GitHub App” is greyed out Only owners and admins of the Oxygen organization can connect a GitHub App installation. Ask one of them to connect it, or use a personal access token. Users see “Sign in with GitHub” but nothing happens Check that GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set correctly. Also verify the callback URL in the GitHub App settings matches your deployment domain exactly. “Use a different GitHub account” connects the wrong account The connect popup opens in a new browser window. If the user is already signed into GitHub as a different account in that window, they may need to sign out of GitHub first before authorizing. After a successful authorization, Oxygen always uses the most recently connected account.