> For the complete documentation index, see [llms.txt](/llms.txt) # Connect a VCS provider To publish your `go` / `swift` / `php` SDKs — and to open regenerate-and-release PRs — Glotto creates a `v` tag (and, later, a PR) directly in your downstream SDK repository through the provider's API. That needs a **connection**: a credential, scoped to your organization, that authorizes Glotto to act on the repos you choose. You connect **once per provider**, and the single connection covers every SDK repo under that account — there is no per-repo setup. > Glotto never stores a long-lived personal access token. Each provider uses its **machine-to-machine** > mode — a GitHub App installation, a GitLab OAuth grant, or a Bitbucket workspace OAuth consumer — and > the at-rest secret (where there is one) is encrypted with AES-256-GCM. A connection is **owner-only**: > only an organization owner can connect or disconnect a provider. ## What Glotto needs, per provider | Provider | How you connect | What Glotto asks for | |---|---|---| | **GitHub** | Install Glotto's [**GitHub App**](https://github.com/apps/glotto) on your org/account and pick the SDK repos | `contents: write`, `pull_requests: write`, `metadata: read` | | **GitLab** | Authorize Glotto's **OAuth application** (one consent screen) | the `api` scope | | **Bitbucket** | Create a workspace **OAuth consumer** and paste its key + secret | `repository: write` | ## GitHub — install the app 1. Start the connection from your organization. Glotto returns a GitHub **App install URL**. 2. GitHub shows the install screen: choose the account and the repositories Glotto may access (the SDK repos you publish to), then confirm. 3. GitHub redirects back to Glotto with the new **installation id**, which Glotto stores against your organization. That's the whole credential — a GitHub App install is not an OAuth token exchange, so there is nothing to paste. If you started from the studio Connections page, your browser is returned there. Glotto's App is published at [`github.com/apps/glotto`](https://github.com/apps/glotto), where you can review exactly what it asks for before you connect. **Begin the install from Glotto, not from that page** — an install started on GitHub arrives with nothing tying it to your organization, so Glotto has no way to record it and no connection appears. If that happens, uninstall it on GitHub and start again from Connections; nothing is lost. From then on Glotto mints short-lived installation tokens on demand; you can change which repos are shared, or uninstall the app, from your GitHub settings at any time. ## GitLab — authorize the OAuth app 1. Start the connection. Glotto returns a GitLab **`/oauth/authorize`** URL (PKCE-protected). 2. GitLab shows one consent screen for the `api` scope; approve it. 3. GitLab redirects back with an authorization `code`, which Glotto exchanges **server-side** for a refresh token. Only the refresh token is kept (encrypted); Glotto re-mints access tokens as needed and rotates the refresh token automatically. If you started from the studio Connections page, your browser is returned there. A denied or cancelled consent connects nothing — you can retry whenever you're ready. ## Bitbucket — submit a workspace consumer Bitbucket's two-legged (`client_credentials`) OAuth has no consent redirect, so you supply the credentials directly: 1. In your Bitbucket **workspace settings → OAuth consumers**, create a consumer with the **`repository: write`** permission. 2. Copy its **key** and **secret** and submit them to Glotto. The secret is encrypted at rest and is never shown again or returned by any API. ## Your own forge identity (optional) The connection above belongs to your **organization**, and Glotto reads with it. You can additionally link **your own** account on a provider, and Glotto will then *write* with yours — so your forge, not Glotto, decides whether a change you make is allowed, and records it as yours. That is what makes a Glotto-opened change count for the controls you already run: - **Branch protection** and **CODEOWNERS** see the person who made the change, not a bot. - The push is authorized by *your* repository permissions, not by an organization-wide grant. Linking is **per person and per organization**, and it needs no admin role — you link your own account, nobody can link it for you, and nobody else can use it. Unlinking takes effect immediately. Glotto stores only the encrypted grant plus the account name the provider reports; it never sees your password and never holds a personal access token. **If you have not linked**, nothing breaks and nothing is hidden from you. The change is pushed with the organization's credential and Glotto records **you** as the commit author, so the history is accurate — but the provider sees the organization, so branch protection and CODEOWNERS will not credit you. Glotto states which of the two carried your change on the same screen, every time. > A per-user grant does **not** make the commit *signed*. It is an ordinary unsigned commit, so it does > not satisfy a signed-commit requirement; what it changes is who the provider sees making the write. Availability differs by provider, and Glotto tells you which are offered on your deployment rather than letting you find out on click: | Provider | Personal identity | |---|---| | **GitLab** | Supported — one consent screen, the same OAuth application as the organization connection | | **GitHub** | Supported — one consent screen on the Glotto GitHub App; Glotto keeps the grant fresh, so you authorize once | | **Bitbucket** | Not applicable — its connection model has no per-person consent step | | **Azure Repos** | Not applicable — its connection is an organization access token | ## Managing connections You can list your organization's connections at any time — each shows the provider, whether it's enabled, and when it was connected, and **never** exposes a secret. Disconnecting a provider removes its stored credential; re-connecting overwrites it, which is also how you rotate the Bitbucket consumer secret. Once a provider is connected, publishing and the [multi-VCS release flow](/docs/multi-vcs-release) use it automatically — a release tags `v` on the target repo (idempotently), and a missing or disabled connection fails the publish with a clear, secret-free message telling you to connect first. ## Connecting is what unlocks a production repository A project builds from the moment it exists: every build lands on the Glotto-hosted **staging repository** for that language, which needs no connection of yours at all — Glotto hosts it. Selecting your **own** repository as a target's production repository is the upgrade a connected organization earns. Glotto refuses the selection until an enabled connection exists for that repository's provider, server-side and not only in the picker, so the answer arrives when you choose the repository rather than at the first failed build. Connect the provider, then select the repository; from then on each build also opens-or-refreshes the release PR there. See [the release flow](/docs/multi-vcs-release) for what the two repositories hold and what a build reports.