Skip to Content

GitHub access

Every GitHub call Screenplay makes, and every push from a chat, needs to know whose credentials to use. GitHub access decides that. It’s a small interface in apps/app/lib/github-access/ with two built-ins:

Built-inToken for API callsGit in a chatFor
oauth-accounteach person’s GitHub sign-inbrokered: each person’s token, commits as themHosted (the default there)
gh-cligh auth tokenthe machine’s own git credentials and identityThe Mac app (the default there), your own box

Both talk to github.com.

The interface

interface GitHubAccess { // A token for the server's own API calls for this person, or null (GitHub features stay off). apiToken(userId: string): Promise<string | null> // How git inside a chat signs in and authors commits. readonly git: | { kind: "host" } | { kind: "brokered" token(userId: string): Promise<string | null> identity( userId: string ): Promise<{ name: string; email: string } | null> } }

With host, Screenplay leaves git alone: it installs no credential helper, rewrites no remote and sets no author, so pushes and commits are whoever the machine’s git is signed in as. With brokered, it hands git the person’s token for each command and sets them as author and committer.

Built-ins

oauth-account

Hosted’s behaviour. The token is the one saved when the person signed in with GitHub.

gh-cli

The Mac app’s behaviour. The token is whatever gh auth token prints, and git uses the machine’s own credentials.

Picking one

selectGitHubAccess() in apps/app/lib/github-access/index.ts picks one: oauth-account when people sign in with GitHub (Hosted), and gh-cli when the host is the only writer (the Mac app, Headless). Set GITHUB_ACCESS to oauth-account or gh-cli to override that. An id it doesn’t know stops the server from starting.

Every replaceable part of Screenplay is picked the same way, like the Yjs host.

Last updated on