# Connect GitHub

> How DiceyTable's GitHub OAuth App works, how linking or creating a repository fits into mod authoring, and why new repositories are created public.

- Source: https://diceytable.com/docs/mods/publishing/github-setup
- Last verified: 2026-07-27

Every DiceyTable mod is a GitHub repository. There is no server-side blob storage for
mod files — your manifest, setup, scripts and assets live in your repo, and everyone
who plays your mod (including you, in the editor) reads them from there. Connecting
GitHub is what lets the in-app editor push commits on your behalf.

## Connecting your account

Open **Edit Mode**, then **Publish** (or the **New Mod** dialog) and choose **Connect
GitHub**. This opens a popup that sends you through GitHub's own OAuth consent screen
for a DiceyTable **OAuth App** — you are never asked to paste a personal access token.
The app requests the `repo` scope, which is what lets it create commits, branches and
repositories on your behalf. When GitHub redirects back, the popup closes itself and
the editor's connection status updates automatically.

Behind the scenes this is a standard three-step OAuth exchange: the editor asks the
server for an authorize URL, GitHub calls the server back with a short-lived code, and
the server exchanges that code for an access token and looks up your GitHub username.
Nothing about this token — or any file it pushes — passes through another player's
browser; it is used only by the DiceyTable server, only to act on your repositories,
only when you publish.

If **Connect GitHub** fails with a "not configured" message, GitHub publishing hasn't
been set up on that server deployment yet — see
[Troubleshooting](https://diceytable.com/docs/mods/publishing/troubleshooting).

## Linking or creating a repository

Once connected, a new mod (or an existing one that isn't linked yet) offers three
choices:

- **No repo yet** — keep authoring locally. Your work lives in the browser's local
  storage until you link a repository; it never leaves your machine and can't be
  checkpointed, published, or played by anyone else in multiplayer.
- **Link existing** — attach an `owner/name` repository you already control. DiceyTable
  does not create it and does not change its visibility.
- **Create new** — DiceyTable creates the repository for you under your GitHub account.

Whichever you choose, the repository is saved on the mod's project record on the
server the moment you link or create it, so you never have to type it in again.

## Why new repositories are created public

When DiceyTable creates a repository for you, it is created **public**, and the New
Mod dialog says so plainly: *"multiplayer peers load mod assets straight from GitHub
raw, so the repo must be public."*

This isn't a stylistic choice — it's load-bearing. When you play a published mod with
other people, **every peer independently downloads the mod's files straight from
GitHub** (`raw.githubusercontent.com`), not from the table host and not from the
DiceyTable server. There is no server-side copy of your assets to fall back to. If the
repository were private, every other player's browser would get an anonymous 404 the
moment it tried to fetch a model, texture, manifest or script — the mod would be
unplayable for everyone except you.

An earlier version of the New Mod dialog implied the opposite — that a linked
repository could be kept private. That was incorrect, and the copy has been corrected
in the product. Treat any documentation, screenshot or old habit that suggests a
private mod repository as out of date.

**If you link an *existing* repository, DiceyTable does not check or change its
visibility for you.** Linking a private repository will let you author and preview the
mod alone (you're authenticated), but it will fail for both the scanner (which reads
your manifest anonymously unless the server itself has been given a token) and for
every other player at the table. Keep a mod's repository public for the whole time it
is meant to be playable in multiplayer.

## What DiceyTable can do with your GitHub access

The `repo` OAuth scope is broad — it's what GitHub requires for creating commits and
repositories on your behalf, and DiceyTable uses it only for that: creating a
repository when you ask for one, and pushing manifest/setup/script/asset commits when
you save a checkpoint or publish. It does not read your other repositories, open
issues, or act on your account outside the mod-publishing endpoints in the editor.

You can revoke access at any time from **Publish → Disconnect**, or directly from
GitHub's own **Settings → Applications** page.

## See also

- [The Publish Flow](https://diceytable.com/docs/mods/publishing/publish-flow)
- [wip and main](https://diceytable.com/docs/mods/publishing/wip-and-main)
- [Troubleshooting](https://diceytable.com/docs/mods/publishing/troubleshooting)
