VD Studio

Appearance

GitHub ​

What's on this screen ​

The GitHub panel configures the singleton GitHub Commit Provider used for delegated Git-backed work. The provider is a GitHub App, not a classic OAuth App.

How to configure GitHub ​

  1. Open Org Settings and select GitHub.
  2. Copy the callback URL shown under GitHub Commit Provider.
  3. Register that exact callback URL on the GitHub App used for commit access and enable expiring user tokens.
  4. Fill in Client ID.
  5. Fill in Client secret.
  6. Paste the App's Private key PEM.
  7. Click Test configuration. Studio authenticates as the App, validates its identity and permission map, and lists the organizations where the App is installed. Testing does not change the saved provider.
  8. Choose the Default organization for Demo Provisioning. Studio preselects the first organization; choose another when needed.
  9. Click Save provider. Studio checks the selection again and saves the provider and its Demo Provisioning target together without opening an authorization popup.

Use the Default organization filter to match any part of a listed organization name, without regard to case. The filter does not change the selected organization until you choose an option; a no-match result is different from an empty or failed organization list.

The form does not ask for App ID or installation ID. The default organization is only for Demo Provisioning; it does not affect Domain repository selection. Install the App into each required organization or personal account from the Domain repository screen, where Studio records the selected installation automatically.

The callback URL shown on this screen is used by the normal user Connect GitHub flow. It is the only GitHub App redirect URL Studio requires. The client secret is exercised during that first user connection.

Ambient Demo Provisioning ​

When AUTH_ENABLED=false, this settings surface is intentionally non-actionable and normal GitHub access continues to use the operator's ambient gh CLI session. To provision demo data in that mode, first configure and save the GitHub App here with authentication enabled. Then set DEMO_GITHUB_ORG in the Ambient deployment to select the Demo Provisioning target organization. Repository creation still uses the configured GitHub App; this environment variable does not affect normal ambient GitHub access.

Required GitHub App repository permissions ​

Configure these exact repository permissions on the App:

PermissionLevelUsed for
AdministrationReadInspecting branch protection
ContentsWriteClone, commit, and push
MetadataReadRepository and branch discovery
Pull requestsWriteOpening and updating pull requests
SecretsWriteConfiguring encrypted GitHub Actions secrets
VariablesWriteConfiguring GitHub Actions variables
WorkflowsWriteCreating or updating workflow files

Do not add Actions or Issues for Studio. Administration: write is required for Demo repository creation and deletion. Workflows: write controls workflow files; it is not permission to administer workflow runs.

When you change an App permission, GitHub requires each existing installation to approve the update. Until approval, a Domain can report an insufficient-permission failure even though the App registration itself shows the new permission.

How to rotate the client secret ​

  1. Open GitHub.
  2. Type the new value in Client secret.
  3. Click Test configuration.
  4. Choose Default organization.
  5. Click Save provider.

If a secret is already saved, Client secret shows Leave blank to keep saved secret. Leaving the field blank keeps the saved secret.

The private key follows the same retention rule. Leave it blank during an update to retain the saved PEM, or paste a replacement key to rotate it.

How to test, save, or archive the provider ​

  • Test configuration validates the exact App identity and all required repository permissions with Client ID + PEM, then lists available organizations without changing the provider.
  • Save provider validates the selected Default organization again, then saves the provider and selection together. It does not replace the active provider when validation fails.
  • Archive keeps the singleton provider row but prevents delegated use until it is reactivated.

If PEM parsing, App authentication, the returned Client ID, the required permission map, or the organization selection fails, the existing provider remains active. Studio shows the safe configuration error returned by the validation. If no organizations are listed, install the App into an organization, then test again. Studio names every missing permission in the error. Correct the App settings, approve the change on existing installations, and test again. If the client secret is wrong, the normal user Connect flow reports the code-exchange failure and creates no user connection.

How Studio writes GitHub Actions secrets ​

The GitHub API supports writing repository secrets even though it never returns their plaintext:

  1. Studio gets the repository's Actions public key from GitHub.
  2. Studio decodes the key as standard padded Base64 and encrypts the secret locally with a libsodium sealed box (crypto_box_seal).
  3. Studio encodes the ciphertext as standard Base64 and sends encrypted_value plus GitHub's key_id to PUT /repos/{owner}/{repo}/actions/secrets/{name}.
  4. GitHub stores the secret. Later API reads expose only metadata such as its name and timestamps, so Studio can determine whether a named secret exists but cannot retrieve its value.

Secret plaintext is never sent to GitHub unencrypted, logged in reconciliation output, or returned from Domain settings.

Repairing a Domain GitHub failure ​

If Domain readiness names the GitHub App:

  1. Confirm the provider passes Test configuration and Save provider on this screen.
  2. Open the App installation in GitHub and approve pending permissions.
  3. Confirm the Domain repository is included in the installation's repository selection.
  4. Return to the Domain and select Retry provisioning.
  5. Reopen the Domain and confirm it remains Active.