SqlDBM App for Github

Overview

SqlDBM can push your model artifacts — DDL scripts, project files — to a GitHub repository. Until now, every git connection carried a GitHub personal access token (PAT) that a user created and pasted into SqlDBM, where it stayed for as long as the connection lived.

The GitHub App replaces that. Instead of holding a long-lived token, SqlDBM asks GitHub for a short-lived credential at the moment of each push, scoped to the single repository being written to. Nothing long-lived is stored in SqlDBM, nothing depends on one employee's personal token, and access is granted and revoked in GitHub by the people who already administer your repositories.

What changes:

• Admins grant SqlDBM access once, choosing exactly which repositories are in scope.
• Modelers stop creating, pasting and rotating PATs.
• Security teams get repository access that is visible in GitHub, revocable from GitHub, and does not outlive an employee's offboarding.

PAT authentication still works. The GitHub App is an additional option you choose per connection, so you can migrate at your own pace.

Before you start

Plan. GitHub App authentication is available on Enterprise subscriptions and on trials. If you don't see the option, check your plan with your SqlDBM account team.

Roles. Setting up the integration is an account-admin task in SqlDBM, done once. Individual modelers don't set anything up; in one of the two setups they authorize their own GitHub account the first time they push, which takes a single click.

On the GitHub side. You need someone who can install an app on the GitHub account or organization that owns your repositories — typically a GitHub organization owner. If you plan to register your own private GitHub App rather than use SqlDBM's, that same person creates it.

Scope of the feature. The GitHub App covers pushing and pulling against github.com. GitHub Enterprise Server and other git providers (GitLab, Bitbucket, Azure DevOps) continue to use their existing authentication.

Choosing your setup

There are two ways to connect, and an account uses one or the other — not both at once. You can switch later by disconnecting and setting up the other.

A rule of thumb. If your security team wants every write to a repository traceable to a named person, and wants SqlDBM to hold no key of yours, use the SqlDBM GitHub App. If you'd rather own the integration outright — your app, your org's audit trail, your key rotation schedule — register your own.

Option A — Connect the SqlDBM GitHub App

An account admin does this once.

1. In SqlDBM, go to Manage → Git integrations.
2. On the GitHub card, choose Connect SqlDBM app.
3. SqlDBM opens GitHub's installation page in a new tab. Choose the account or organization that owns your repositories.
4. Select the repositories SqlDBM may reach. You can grant all repositories or pick specific ones; only the repositories you grant here can ever be written to.
5. Confirm the installation. GitHub returns you to the Git integrations page, which now shows the app as connected.

That's the whole admin setup. Each modeler then authorizes their own GitHub account the first time they push — see Authorizing your GitHub account below.

If the Connect button isn't there. The SqlDBM app is enabled per environment. If your environment doesn't have it, the button is hidden and you'll only see the option to register your own app. Contact SqlDBM support if you expected it to be available.

Option B — Register your own GitHub App

An account admin does this once. There are two paths: register an app that a GitHub admin creates in the usual way, or have SqlDBM pre-fill GitHub's creation form for you. Which one is open to you depends on who holds app-creation rights in GitHub.

Manual

This path works no matter who holds permissions in GitHub. The app is created in GitHub by a GitHub admin, separately and at their own pace — they don't need a SqlDBM account, and you don't need GitHub rights. They hand you three things, and you register them in SqlDBM.

1. A GitHub admin creates the app on the account or organization that owns your repositories, following the checklist in Permissions SqlDBM requests below, and downloads its private key (the .pem file).
2. They pass you the App ID, the app slug (the name as it appears in the app's GitHub URL), and the .pem file.
3. In SqlDBM, go to Manage → Git integrations → connect your private GitHub app and set Installation type to Manual.
4. Enter the App ID and slug, and paste the contents of the .pem file. Save.
5. SqlDBM verifies the key against GitHub and rejects the pair if they don't match, so a typo fails here rather than at push time.
6. SqlDBM then sends you to the app's installation page. Select the repositories the app may reach, and confirm. If the GitHub admin already installed the app, confirm the repository list is complete.

Create from manifest

On this path SqlDBM pre-fills GitHub's app-creation form with the right permissions, so there is nothing to configure by hand.

This requires the SqlDBM admin running it to also hold app-creation rights in GitHub — an owner of the target organization, or the owner of the personal account the app will live under. Without those rights GitHub refuses at the creation step. If SqlDBM admins and GitHub admins are different people at your company, use the manual path instead.

1. Go to Manage → Git integrations and choose connect your private GitHub app.
2. Set Installation type to Automatic · Manifest.
3. If the app should belong to an organization rather than your personal GitHub account, enter the organization's login name.
4. Continue to GitHub. Review the pre-filled form and click Create GitHub App.
5. GitHub returns you to SqlDBM, which stores the app's credentials and then sends you to the app's installation page.
6. Select the repositories the app may reach, and confirm.

Installing matters as much as registering. Registering tells SqlDBM which app to use; installing tells GitHub which repositories that app may touch. A repository that isn't part of the installation will fail to push even though the app is connected.

Authorizing your GitHub account

This applies only when your account uses the SqlDBM GitHub App. With your own private app there is no per-user step.

There is no "Authorize" button to hunt for. The first time you do something that needs GitHub — saving a GitHub App connection, opening push settings, or pushing — SqlDBM opens a GitHub tab asking you to authorize the SqlDBM app for your account. Approve it, and the tab closes itself and your action continues.

A few things worth knowing:

• Allow pop-ups for SqlDBM. The authorization window is a pop-up. If your browser blocks it, SqlDBM tells you so; allow pop-ups for the SqlDBM domain and try again.
• You authorize once. After that, SqlDBM keeps your authorization current on its own. You'll only be asked again if you remove it, an admin disconnects the integration, or you revoke SqlDBM's access from your GitHub settings.
• You push as you. Commits SqlDBM makes on your behalf carry your GitHub identity, and reach only the repositories that both the installation covers and you can already access in GitHub. Authorizing does not widen your GitHub access.
• Where to check. Your current status, including the GitHub account you're linked to, is shown on the connection screens in SqlDBM.

Using the GitHub App on a connection

Once the integration is connected, each git connection chooses its own authentication method.

1. Open the connection (new or existing) in Manage connection.
2. Under Authentication, choose GitHub App instead of Personal access token. The token field disappears — there is nothing to paste.
3. Point the connection at the repository as usual and save.

Notes:

• The GitHub App option is greyed out until an admin has connected an app for the account. Hover it for the reason.
• GitHub App connections must use a github.com repository, and cannot also carry a personal access token.
• Switching an existing connection from PAT to GitHub App doesn't change its history, branch, or target repository. Only how SqlDBM authenticates changes.
• If the connection is set to open a pull request on push, make sure the app's permissions include pull requests (see the next section).

Permissions SqlDBM requests

Both setups ask GitHub for the same three repository permissions, and nothing else.

These are a ceiling, not a grant. Each credential SqlDBM mints carries only what the operation in front of it needs — a connection that doesn't open pull requests never receives a pull-request-capable credential — and reaches only the one repository being written to.

SqlDBM asks for no organization permissions, no account permissions, and no webhooks. It cannot read repositories outside the installation you granted, cannot see your other GitHub organizations, and receives no events from GitHub.

Checklist for a manually created app

If you create your own app by hand rather than using the automatic path, match this. (The automatic path sets all of it for you.)

Managing access

See who can push

On the SqlDBM GitHub App, admins can view the list of users who have authorized their GitHub account and which GitHub login each pushes as, from Manage → Git integrations. This is the "who pushes as whom" view your auditors will ask for.

Remove your own authorization

Any user can remove their own authorization from the connection screens. SqlDBM deletes the stored credential and asks GitHub to revoke it. Your next push will prompt you to authorize again.

When someone leaves

Removing a user from your SqlDBM subscription also removes their GitHub authorization and revokes it at GitHub. No separate cleanup step is needed.

Disconnect the integration

Admins can disconnect from Manage → Git integrations, with a confirmation prompt. Disconnecting removes the registration and every user authorization under it, and revokes those credentials at GitHub. Connections set to GitHub App authentication will stop pushing until an app is connected again, so plan this as a change, not an experiment.

You can also remove access from the GitHub side at any time — uninstall the app, or narrow the repositories it covers — without touching SqlDBM. GitHub is the source of truth for what SqlDBM can reach.

One note on revocation: if the same GitHub identity is authorized in more than one SqlDBM account, SqlDBM won't revoke the underlying GitHub grant, because doing so would break the other account. It will tell you when that happens.

How your credentials are protected

For security reviews, the short version:

• No long-lived tokens. SqlDBM mints a credential when a push happens and lets it expire. There is no stored PAT to leak, and no token that outlives its purpose.
• Scoped to one repository at a time. Each credential is issued for the single repository being written to, carrying only the permissions that operation needs.
• Encrypted at rest, bound to your account. Every secret SqlDBM stores — an app private key, or a user's GitHub credential — is encrypted with AES-256-GCM and cryptographically bound to your account (and, for user credentials, to that user). Ciphertext moved anywhere else simply won't decrypt.
• Never displayed, never logged. Private keys and tokens are never returned by the API, never shown in the UI after entry, and are redacted from logs, error messages and telemetry.
• With the SqlDBM app, we hold no key of yours. That setup uses each user's own GitHub authorization; there is no shared key that could reach your repositories, and tenant isolation is enforced by GitHub's own access control.
• Access is revocable from GitHub. Uninstalling the app or narrowing its repository list takes effect immediately, independent of SqlDBM.

Troubleshooting

"Installation unavailable" when pushing. The repository isn't covered by the app's installation. In GitHub, open the app's installation settings and add the repository to the granted list.

The GitHub App option is greyed out on a connection. No app is connected for the account yet. An admin needs to complete Option A or Option B first.

The authorization window never opens. Your browser blocked the pop-up. Allow pop-ups for the SqlDBM domain and retry the action.

You're asked to authorize again. Expected after you remove your authorization, after an admin disconnects or replaces the app, or after you revoke SqlDBM from your GitHub account settings. Approve once and pushes resume.

A push fails with an authorization error. GitHub rejected the credential, usually because access was revoked in GitHub. SqlDBM discards it and will ask you to authorize again on your next attempt.

Saving a manual registration is rejected. The App ID and private key don't belong to the same app, or the key isn't a valid private key. Re-download the .pem from the app's GitHub settings, confirm the App ID on the same page, and try again.

Pull requests aren't being created. The app is missing the pull-requests permission. Update it in GitHub and accept the permission change on the installation.

FAQ

Do we have to migrate off personal access tokens? No. PAT authentication remains supported, and you choose per connection.

Can we use both setups at once? No. An account uses either the SqlDBM app or its own private app. Switching means disconnecting one and setting up the other, which requires users to re-authorize if you move to the SqlDBM app.

Who appears as the author of commits? With the SqlDBM app, the user who pushed. With your own private app, the app itself, acting for the account.

Can SqlDBM reach repositories we didn't grant? No. The installation you configure in GitHub is the boundary, and on the SqlDBM app each user's own GitHub access narrows it further.

Does SqlDBM receive webhooks or watch our repositories? No. The app subscribes to no events. SqlDBM only contacts GitHub when an action in SqlDBM requires it.

Does this work with GitHub Enterprise Server? Not currently. GitHub App authentication covers github.com. Continue using existing authentication for other hosts.

What happens if we rotate the app's private key? Save the new key in SqlDBM through the manual registration form. Credentials minted with the old key stop being used immediately.

Is this related to signing in to SqlDBM with GitHub? No. This is about pushing to repositories. Signing in to SqlDBM is handled by your SSO configuration.