Connecting a repository

Midstream reads your repository, so before anything works you install our GitHub App and link a repository to a project. There are two ways in, depending on whether you start from GitHub or from Midstream. Both end in the same place.

How the pieces fit

A workspace is your team. It owns members, API keys, billing, and the GitHub App installation. Most companies need exactly one.

A GitHub App installation is the permission to read a set of repositories. You install it once per workspace, choosing an account or organization and which of its repositories we may see. A workspace can hold more than one installation — your organization and your own account, say.

A project is one repository. Each project has its own scenes, its own history, and its own URL at midstream.studio/your-workspace/your-project. A repository belongs to at most one project.

Starting from GitHub

This is the path a new account takes.

1. Sign in with GitHub.
2. Because you have no workspace yet, we send you straight to GitHub to install the app. Choose the account or organization, and either all repositories or a list you pick.
3. GitHub sends you back to Midstream. We check the installation is yours before accepting it (see below).
4. Name your workspace. The field is pre-filled with the organization you just installed into.
5. Pick a repository and name the project. The name becomes the URL, and we tell you if it is taken.

The installation is attached to the workspace at the moment you create it, so you land on project creation with your repositories already listed.

Starting from Midstream

If a workspace exists but has no installation — someone created it before connecting GitHub, or you are adding a second organization — go to Settings → Integrations. Under GitHub, press Connect GitHub. That sends you to the same GitHub install screen, and back to your workspace afterwards. Then Add project and pick a repository.

Settings → Integrations is also where you go later: each installation lists the account it belongs to, how many repositories it covers, and a Manage on GitHub link for changing that list.

What we check when you install

When GitHub sends you back, the request names an installation, and we do not take that on trust. We ask GitHub who the installation belongs to, and:

• For an installation on a personal account, it has to be your account.
• For an organization, you have to be a member of that organization. We check with GitHub directly, so it works whether your membership is public or private.

If neither holds, we refuse and say why, and nothing is linked.

When the installation is already taken

An installation belongs to one workspace. If you install the app for an organization that is already connected:

• If you are a member of that workspace, we take you to it. Nothing is duplicated — your organization is already set up, and the project you want may already be there.
• If you are not a member, we stop: "This GitHub account is already connected to another Midstream workspace. Ask a member of that workspace to invite you." That is the fix. Someone already in the workspace invites you, rather than a second workspace being created for the same organization.

If a repository is missing from the list

The picker shows only repositories the installation can see. If yours is not there, the app was not granted access to it. Go to Settings → Integrations → Manage on GitHub, add the repository, then come back and press the refresh button next to the picker. We re-read the list from GitHub on demand, not on a schedule.

What we ask GitHub for, and why

• Read your code. We clone the repository at the exact commit a capture was made from, in order to run it.
• Read pull requests. To know which scenes a pull request touches, and which files changed between two commits.
• Write check runs and deployments. So a pull request carries a Midstream check and a link into the review view.
• Read organization membership. Only to verify that whoever installs the app belongs to the organization they are claiming.

We do not write to your repository's contents: nothing pushes a branch, edits a file, or opens a pull request.

What happens after you connect

Nothing automatic — connecting a repository does not change your code. Three steps, and you can do them in any order:

1. Install the SDK: npm install --save-dev @midstream/sdk.
2. Mark a scene in a Playwright test with midstreamScene(). (The function keeps its old name for now; it marks a scene.) See The scene call.
3. Add midstream.json to your repository root.

Then push. Your CI run registers the captures, and the project fills in. If your tests run on GitHub Actions there is nothing else to configure — Running Midstream in CI covers what the run needs.