Skip to content

Connect GitHub

Install your GitHub App on the repositories you choose, review its permissions and events, and connect each project to a repository, branch and folder.

Why a GitHub App

SpecsGraph writes to your repository through a GitHub App, not through a person's account or a deploy key. That choice keeps its access small and easy to see.

  • Per-repository access. You pick the repositories the App can reach during installation. Every other repository in the account or organization stays invisible to SpecsGraph.
  • Least privilege. The App asks for the few permissions it needs to publish, listed below, and nothing else.
  • Short-lived credentials. GitHub issues the App installation tokens that expire after an hour. There is no long-lived secret tied to one engineer that breaks when they leave.
  • A clear author. Spec commits and pull requests come from the App's own bot account, such as specsgraph-northwind[bot] for an App named SpecsGraph Northwind, so they are easy to tell apart from human commits in the log.

Install the App

The App is the one you registered for your install in Create your GitHub App. An Admin or Owner installs it once per workspace, and every project in the workspace then uses that installation.

  1. Start from SpecsGraph

    Open Workspace settings, then GitHub and choose Connect GitHub. SpecsGraph sends you to GitHub.

  2. Pick the account or organization

    Choose where your repository lives, for example the northwind organization. If you are not an owner of that organization, GitHub sends the installation to an owner as a request, and the steps continue once they approve it.

  3. Select repositories

    Choose Only select repositories and pick the ones SpecsGraph should publish to, such as northwind/shop. You can add more later without reinstalling.

  4. Install and return

    GitHub shows the permissions below. Confirm them, and GitHub returns you to SpecsGraph with the installation connected.

Note

GitHub's own documentation is the authority on its screens and on installation requests. The steps here describe GitHub at the time of writing.

Permissions and events

PermissionAccessWhy SpecsGraph needs it
ContentsRead and writeWrite the spec folder and create proposal branches.
Pull requestsRead and writeOpen a pull request for each approved proposal.
MetadataReadList repositories and branches you choose to connect.

GitHub does not offer permissions scoped to one folder, so contents access covers the whole repository. SpecsGraph only writes inside the spec folder of each connected project, and every write is a commit you can inspect.

Webhook events

EventWhat SpecsGraph does with it
installationLearn when the App is installed, suspended or uninstalled, so SpecsGraph knows whether it can publish.
installation_repositoriesLearn when repositories are added to or removed from the installation, so the repository picker stays current.
pushNotice when a base branch moves, so open spec/ branches can be rebased, and spot commits to the spec folder made outside SpecsGraph.
pull_requestFollow the pull requests SpecsGraph opened: merged, closed or reopened. A merge marks the proposal Published.

The App does not ask for issues, Actions, secrets, checks or administration permissions. It cannot change branch protection, read your Actions secrets or see repositories you did not select.

Connect a project to a repository

Each project publishes to one repository. You set that up when you create the project, or later in its settings. Workspaces and projects walks through project creation; these are the settings that concern GitHub.

SettingWhat it controlsNorthwind Commerce example
RepositoryWhere commits and pull requests go. Only repositories in the installation appear.northwind/shop
Base branchThe branch proposal branches start from and pull requests target. Defaults to the repository's default branch.main
Spec folderThe only folder SpecsGraph writes to.specsgraph
Publish modePull request (the default) or Direct commit. See Branches and pull requests.Pull request

Nothing is written until the first proposal is approved. Connecting a repository does not create a branch, a commit or a pull request.

Monorepos

Several projects can publish to one repository if each has its own spec folder, for example apps/shop/specsgraph and apps/warehouse/specsgraph. Each project writes only inside its folder, and each proposal still gets its own branch, so two projects never share a pull request. One installation covers all of them.

Change or remove access

Repository access is managed in GitHub. Open the settings of the account or organization that installed the App, find SpecsGraph among the installed GitHub Apps and choose Configure. From there you can add or remove repositories, suspend the App or uninstall it.

  • Removing a repository stops publishing for every project connected to it. Those projects show a warning, and approved proposals wait until access returns or the project points elsewhere.
  • Suspending or uninstalling stops publishing for the whole workspace. The graph, proposals and history stay in SpecsGraph.
  • Neither deletes anything in Git. Files already in specsgraph/ and open pull requests stay where they are.

Where the App comes from

Each self-hosted install uses its own GitHub App, because GitHub sends an App's webhooks to a single URL. You register it with the permissions and events above, and give its credentials to your install through GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY_PATH and GITHUB_APP_WEBHOOK_SECRET; Create your GitHub App has the full walkthrough. SpecsGraph Cloud, which is coming soon, will offer an App run by SpecsGraph instead.

Next steps