Access and identity

Signing in#

People sign in through Keycloak (OIDC). Only the control plane is a client of Keycloak. The web app keeps an opaque session in an httpOnly cookie and never sees Keycloak's tokens, and signing out also ends the Keycloak session.

• Session revocation: users disabled or deleted in Keycloak lose every session, token and SSH key within a minute or two.
• Site admins: Keycloak's branchscope-admin role makes a site admin. Site admins see every repository and administer each one, and change any organization's settings, SSO included. Under Admin in the sidebar they control the push guard and the hosted runners (/hosted-runners: the machines, and which accounts and organizations may use them, with how many hosted jobs each may run at once), and, where the server sets it up (ACCOUNTS_URL), open Keycloak's admin console (Accounts), where people's accounts are made and disabled. They edit the docs in the CMS at /cms, and they get the messages people report in Chats.

Passkeys#

A passkey signs you in with your fingerprint, your face or your device's PIN instead of your password. It's made on your device and kept there (or in your password manager), and only works on Branchscope's sign-in page, so it can't be phished or reused elsewhere. Keycloak keeps the passkey's public half and checks every sign-in; Branchscope never sees any of it.

• Signing in: on the sign-in page, pick your passkey from the suggestions under the username field, or choose Sign in with a passkey. To use a phone, choose its option in your browser's passkey window and scan the QR code.
• Adding one: Settings → Privacy and security → Passkeys → Add a passkey. Keycloak may ask you to sign in again first (if you signed in more than five minutes ago), then asks you to name the passkey and create it. You come back to Settings, where it's listed.
• Renaming and removing: in the same list, which also shows when each was added and last used. Removing a passkey doesn't sign you out anywhere.
• The last way to sign in can't be removed: with no password and no linked identity, your only passkey stays until you add another passkey or a password. With exactly one passkey and nothing else, Settings suggests adding a backup on another device.
• Passkeys are for people in a browser. Tokens, agents and apps can't list, add or remove them.

A passkey takes the password's place when you sign in; it isn't a second factor, and your password, if you have one, still works.

Recovery#

If you lose every passkey:

• sign in with your password, if you have one, and add a new passkey;
• or sign in through your organization's provider, if your account is linked to one;
• otherwise ask a site administrator. In Keycloak's admin console (Users → you → Credentials) they can remove the lost passkeys, set a temporary password, or ask you to register a new passkey at your next sign-in.

There's no reset by email.

Who can do what#

A person's access to a repository is the highest of:

Source	Access
The repository is public	read, for anyone
You own it	admin
Owned by an organization you own	admin
Owned by an organization you're a member of	read
You're a collaborator	the role you were given: read, write or admin
You're a site admin	admin

Access	Lets you
read	clone, fetch, browse, read changes, reviews and graphs
write	push, open, merge and close changes, build graphs
admin	settings: visibility, rulesets, environments, secrets, mirrors, integrations, AI provider keys, caches, collaborators, setup commands, the audit log

Organizations#

Create one from the namespace switcher at the top of the sidebar (New organization). Organization owners add members; members read every repository of the organization, and get write or admin per repository as collaborators. Owners see the organization's audit log, with every one of its repositories' entries.

An owner deletes an organization under its Settings → Privacy and security (Delete this organization), after typing its name: its repositories, apps, members, runners and webhooks go with it, and it can't be undone. Its name is free again afterwards.

Owners, and site admins, manage an organization in its Settings: its profile, members, apps, runners, secrets, webhooks, integrations, audit log, services, SSO, and privacy and security.

Single sign-on#

An organization can have its people sign in with the identity provider it already runs: Microsoft Entra ID, Google Workspace, Okta, or any other OIDC provider. Keycloak brokers the sign-ins; Branchscope never sees the provider's passwords. Owners set it up under the organization's Settings → SSO. SAML and SCIM provisioning come later.

Connecting a provider#

1. At the provider, register an app (a web application, with a client secret) whose redirect URI is the one Settings → SSO shows: https://<Keycloak>/realms/branchscope/broker/org-<organization>/endpoint.
2. In Settings → SSO, choose the provider and enter its issuer (or its …/.well-known/openid-configuration), the client ID and the client secret. For Entra ID, use your tenant's issuer, https://login.microsoftonline.com/<tenant ID>/v2.0, not common. For Google, enter your Workspace domain too, so only its accounts get in.
3. Test the connection: you sign in through the provider once. Until an owner has, it can't be turned on. Changing where the provider is or its client means testing it again.
4. Turn it on.

The client secret is encrypted (with the server's SECRETS_KEY), handed only to Keycloak, and never shown again. Leave the field empty to keep it.

Verified domains#

Prove the organization owns a domain by adding the DNS record Settings → SSO shows, then Verify:

Type	Name	Value
TXT	_branchscope-challenge.acme.com	branchscope-domain-verification=<token>

Once a domain is verified, Sign in with SSO on the sign-in page sends anyone who types an email on it (@acme.com, not its subdomains) to the organization's provider. A domain can be verified by one organization only.

Linked identities#

Your account at a company's provider is linked to your Branchscope account, once, after you confirm it's you: you're signed in when you link it, or Keycloak asks for your password. A person keeps one Branchscope account across organizations. Signing in through an organization's provider makes an organization session for that organization only; your other organizations and your own repositories stay as they are.

Settings → Linked identities lists yours, with the organizations you could link, and unlinks them. One that's the only way you sign in stays until you set a password or add a passkey.

Requiring SSO#

An owner can require SSO once the provider is on and they have signed in through it themselves. Then, for members:

• In the web app, the organization's repositories, and its owner pages, need an organization session. It lasts the hours the organization sets (24 by default) and belongs to the browser session it was made in. Without one, the organization's page offers Sign in with the provider.
• Tokens, SSH keys and agents reach its repositories while their person is linked to the provider. Unlinking, by the person, by an owner removing the provider, or in Keycloak, stops them at once.
• Not held to it: outside collaborators, apps the organization installed, read access to public repositories, and site administrators.

A passkey signs you in to Branchscope, but doesn't make an organization session: that still needs a sign-in through the organization's provider, as after a password.

Settings → SSO shows who has linked their account and when each last signed in through the provider. While SSO is required, changing those settings needs an organization session; a site administrator can always change them, to recover from a broken provider.

Just-in-time membership#

Off by default. When it's on, someone who signs in through the provider with an email on one of the organization's verified domains joins as a member.

What's recorded#

The organization's audit log records the provider being set or removed, its test, domains added, verified and removed, sign-ins through the provider, just-in-time members, and identities linked and unlinked. Linking and unlinking are on the person's own log too. Never a secret.

Your account#

Settings (from your avatar at the bottom of the sidebar, or /settings) has your account's tabs: Profile, Preferences, Services, Privacy and security, Linked identities and Audit log.

• Profile: your avatar (PNG, JPEG or WebP, up to 256 KB), name, bio (up to 180 characters), company, location, local time, up to 4 websites and one account on each social network, and whether your email shows. They're on your page, /<username>. Branchscope keeps your avatar and serves it itself, so pages never load images from elsewhere.
• Preferences: the language, used for Branchscope and its sign-in page, and the theme (light, dark, or as your system). Both are kept in this browser.
• Privacy and security: your passkeys, and the people you blocked from messaging you.

Signed out, the language picker is at the bottom of the sidebar. The language you choose wins over your browser's.

An organization's profile#

On an organization's Settings → General, its owners set its name as written (its namespace doesn't change), its picture (as for an avatar), bio, location, website, LinkedIn page and a public email. Under Settings → Privacy and security they choose which tabs its page shows (Repositories and Members), and can delete it (see Organizations).

The API#

These need a web session; tokens, agents and apps can't change a profile.

PUT /me/profile	your profile; only the fields sent change
PUT, DELETE /me/avatar	upload your avatar ({image}, base64), or remove it
PUT /orgs/{org}/profile	an organization's profile, and its tabs (showRepositories, showMembers): owners and site admins
PUT, DELETE /orgs/{org}/avatar	upload or remove an organization's picture
DELETE /orgs/{org}	delete an organization, with everything in it

Tokens#

Personal tokens (bsc_pat_…) are how git, scripts and the CLI authenticate as you. Make them under Tokens, or with bscope token create.

• Limits: a token can be read-only, limited to some repositories, and set to expire. Limits only ever narrow what its owner can do.
• Agents don't use them. An agent signs in on its own, with bscope agent login or as an installed OAuth app, so everything it does is recorded as the agent's. See Agents.
• Shown once: a token is shown once and stored only as a hash.
• Creating them: only a signed-in person, in the web app, can create tokens. The CLI's token create opens the browser to approve. Tokens can't create tokens.
• Revoking them: with a session or a personal write token, never with an app's or a read-only token.

SSH keys#

SSH keys work like tokens: read-only, limited to repositories, expiring. They're for people; agents push over HTTPS (bscope agent setup-git).

• Key types: Ed25519, ECDSA (P-256/384/521), and RSA of 3072 bits or more. The server refuses SHA-1 (ssh-rsa) signatures.
• One account per key: a key can belong to only one account.
• Adding keys: under SSH keys, or with bscope ssh-key add, which is approved in the browser and shows the key's fingerprint to check.
• Verifying the server: the SSH keys page shows the server's host key fingerprint, to check on your first connection.

Signing in from the CLI#

bscope auth login opens the web app; you approve, and the CLI receives a token for this computer. How the handoff works:

The token never appears in a URL or in the browser's history, and the code works once, only with its state.