Connect a repository

Before an agent can read a line of your code, the workspace has to know where the code lives. Connecting a repository is that step: you tell Disco Parrot the clone URL, which branch to start from, and which provider credential reaches it, and from then on the repository is something a sandbox can clone, an agent can work against, and a pull request can land back into.

This page is the how-to for connecting one. It assumes you have a repository provider configured already, because a repository always belongs to a provider; the provider holds the credential, and the repository points at it. If you have not set one up yet, start there and come back. The split is deliberate: the provider is the access decision your admins make once, and the repository is the cheap, repeatable part you do per service. One credential, many repositories pointed at it.

What a connected repository is

A connected repository is a small record in your workspace, not a copy of your code. Disco Parrot does not mirror your Git history or hold your source between runs. The record carries what a sandbox needs to fetch a fresh clone on demand: a name, the provider it authenticates through, the clone URL, the branch to start from, an optional clone depth, and a set of tags you choose. When an agent needs the code, the sandbox clones it at run time using the provider's credential, works against that clone, and the clone goes away with the sandbox. The record stays; the working copy is disposable.

The clone is not cached, snapshotted, or copied out. It exists only inside that one sandbox, and when the sandbox is torn down the working copy goes with it. That means there is no stale checkout to drift from your branch and no second copy of your source for anyone to find: the next run starts from a fresh clone, never a leftover one.

That shape is the point. Your code stays in GitHub, where it already lives and where your team already governs it. The workspace holds a pointer and a credential reference, never the repository itself, so connecting a repository adds a route to your code rather than a second home for it.

Add a repository

You add a repository from the Repositories area under Platform. Adding and editing are the same form, and the fields divide into four parts: what the repository is, how it authenticates, where its code is, and how you label it.

Name and identifier

A repository needs a name, which is how it reads everywhere in the product, and an identifier, the short slug that addresses it in URLs and in sandbox mount paths. You do not type the identifier separately. As you name the repository, Disco Parrot derives the slug from the name, lowercasing it and replacing anything that is not a letter or digit with a hyphen, so Insights API becomes insights-api. You can adjust the slug while you are creating the repository, but once you save it, the identifier is fixed. It is the stable handle the rest of the workspace uses to refer to this repository, so it does not move out from under a sandbox profile or a doc-health schedule that points at it.

A description is optional and is there for the next person, the one reading the list of repositories six months from now trying to remember which service this is.

The provider it authenticates through

Every repository points at a provider, and the provider is what makes the clone authorized. You pick it from a dropdown that shows each configured provider with its kind, its auth method, and a live status: a green dot and Connected as @login when a credential is in place, a grey dot and Not configured when one is not. If you select a GitHub provider that still needs a credential, the form gives you an inline panel to connect one without leaving the page. A GitHub Enterprise provider sends you to its own page to connect, since enterprise sign-in is a redirect through your identity provider rather than something the repository form can hold inline.

If you have not made a provider yet, the form offers to create one. The order is deliberate: the provider holds the credential and the policy around it, and the repository is the thing that uses them. Connecting code is a two-part idea on purpose, one part about access and one part about the specific repository, and the next page covers the access half in full.

Where the code is

The Git URL is the clone URL, the same https://github.com/owner/repo.git you would hand to git clone. The platform clones over HTTPS because the credential it mints is a short-lived HTTPS token scoped to that one operation, so an HTTPS URL is what you want here. There is no SSH key to mint, rotate, or leave sitting on a host.

For a plain GitHub provider, you do not have to type the URL at all. A Pick from provider button browses the repositories the credential can already see, the hundred most recently updated, with a filter box over the names and a lock on the private ones, and fills the clone URL and default branch for you when you choose one. If the repository you want is older than the recent hundred, the filter will not find it; that is the moment to paste the URL by hand instead. A GitHub Enterprise provider, whose repository list is not dependably enumerable, leaves the button off and expects a pasted URL, which is the one place the two providers differ at connect time.

The default branch is where work starts. Leave it blank and the clone follows the repository's own default branch, whatever GitHub reports as HEAD. Set it explicitly when an agent should start from something other than that, a long-lived integration branch, say. This is the branch a sandbox checks out unless a sandbox profile overrides it for a particular setup.

Clone depth is a performance dial. Leave it empty for a full clone with the entire history, or set a small number for a shallow clone that fetches only the most recent commits. A shallow clone is faster to set up and lighter on the sandbox, and most agent work reads the current state of the code rather than spelunking through years of history, so it is usually all the agent needs. As with the branch, a sandbox profile can override the depth for a given setup; the value here is the default the workspace falls back to.

Tags

Tags are free-form labels you attach to a repository, lowercased and de-duplicated as you add them. They are how you group repositories that belong together: the three services behind one product, the repositories one team owns, the set you think of as the data platform. A tag is yours to define; the product does not impose a taxonomy, it gives you a place to put your own.

A tag earns its keep the moment the list grows. With four repositories you remember which is which; with forty you filter. Tagging checkout across the three services behind one product, or payments-team across everything one team owns, turns the flat list into something you can narrow to the slice you mean. You define the taxonomy because you are the one who has to find things in it later.

Confirm the connection before you rely on it

A clone URL and a credential can both look right and still not reach the code. The credential might not be authorized for this repository, the GitHub App might not be installed on the owner, the URL might point somewhere the token cannot see. Test Connection is how you find out before an agent does. It is not a lighter-weight check that stands in for the real one; it is the real one, run early.

Once a repository is saved, the form shows a Test Connection button, and it does the real thing, not a dry run of it: the platform resolves the provider's credential the same way a sandbox will, normalizes your URL to an HTTPS clone URL, and runs git ls-remote against the remote to confirm the credential can actually list the repository's branches. It is the same authentication path the sandbox uses to clone, so a green result here means a green clone at run time, not an approximation of one.

When it works, you get a plain confirmation that the credential reached the repository. When it does not, you get more than a red X. For a GitHub repository, the platform asks GitHub why and turns the answer into something you can act on. Each failure points at a different fix, which is the reason the platform bothers to name it:

• Credential rejected means the provider has no working credential. Open the provider and reconnect it, or pick the right identity in the identity picker.
• Visible, but no push access means the credential can read the repository but not write to it. An agent that only reads is fine; one that opens a pull request is not, so widen the App installation's permissions or the token's scope before you ship from this repository.
• Not found almost never means the repository is gone. It means the GitHub App is not installed on that owner, or its installation was scoped to a set of repositories that does not include this one. Install the App on the owner, or add this repository to the installation's selected list.

The failure tells you which knob to turn, so a broken connection is a five-minute fix you make at your desk rather than the same failure surfacing mid-Flow, where it costs an agent run and your attention to diagnose.

Put documentation on a schedule

Connecting a repository is also where you decide whether its documentation keeps itself current. A repository's settings include a documentation health review, a scheduled Flow that reads the repository and the recent work against it and proposes edits to the repository's docs where they have drifted. The full review, what it proposes and how you approve its edits, is its own subject under repository documentation. What you set here is the schedule.

The schedule has a handful of dials:

• Frequency is how often the review runs, from a few times a day down to twice a month, picked from a set of presets or written as a custom schedule. A time of day and a timezone go with it, so a review lands when someone is around to look at what it found rather than at three in the morning.
• Lookback is how far back the review reads, in days. A weekly review with a seven-day lookback sees the week that just happened; a longer window catches slower drift.
• Minimum sessions is the quiet-week guard. It sets how much agent work has to have landed before a review is worth running, counted in sessions, so a week where almost nothing happened does not turn up a batch of thin suggestions nobody asked for. You put the bar where a review's findings would be worth your attention.
• Auto-apply high-confidence proposals records how hands-on you want to be with what a review turns up. The review itself proposes and a person approves, and where you walk a batch and approve its edits is the repository's documentation health reviews, where the high-confidence column is the lever for moving fast on the obvious changes.

Between them, the activity bar and the auto-apply preference are how you tell a review how selective to be and how much you want to read by hand. Most teams start with a weekly schedule and a lookback to match, then settle their oversight as they see what a few cycles turn up. The schedule is the rest of the connection's character: you are not only telling Disco Parrot where the code is, you are deciding how closely its documentation keeps pace with the work, and you are deciding it in the same place you set the branch and the depth.

The full review, its proposals and the surgical edits you approve or reject, lives on the repository's own Health Reviews tab, covered under documentation health reviews. Next to it sits a Documentation tab that holds the pages themselves, where you write, organize, and onboard a repository's docs, covered under repository documentation and wiki. Both tabs appear once the repository is saved, alongside Settings.

A repository is a workspace resource

A connected repository belongs to the workspace, not to the person who added it, and not to the one credential it was first tested with. Everyone in the workspace works against the same set of connected repositories, and the credential each person uses to reach one is resolved per person through the provider, so a shared repository does not mean a shared key. Adding, editing, and removing repositories is administrative work, held by the repositories.manage scope that your admins, owners, and workspace operators carry. Reading the list of connected repositories rides on repositories.read, which every member and viewer has, so anyone can see what the workspace is connected to while only the right people can change it.

Removing a repository removes the workspace's pointer to it, not the code. The repository on GitHub is untouched; what goes away is Disco Parrot's route to it. The one thing to know before you remove one is that a sandbox profile still listing the repository will fail to launch until you point it somewhere else, which the confirmation tells you up front.

Connecting many repositories

One repository is the easy case. A real workspace connects a service at a time until it has a dozen, and the model is built so the tenth costs the same as the first. The provider is the part you set up once; every repository after that is a name, a URL, a branch, and the same provider picked from the dropdown. There is no per-repository credential to mint, no key to hand out, and no access review that grows with the list, because the access decision was made once at the provider and every repository inherits it.

Tags are how that list stays legible past the point where you can hold it in your head. Tag the three services behind one product, tag everything one team owns, and the flat roster of repositories becomes something you filter to the slice you mean. The list view carries the tags on each row, so finding the data-platform repositories is a filter, not a memory test.

Where a set of repositories becomes a working environment is the sandbox profile. A profile names the repositories an agent should have on hand for a kind of work, the front end and the API and the shared library that all change together, and pulls each one in at run time through its provider. It names them one by one, each the specific repository you connected here, so the profile is an explicit, readable list of what travels together rather than a query you have to trust. You connect each repository once, on this page; the profile is where you decide which ones an agent sees at the same time.

A repository, connected end to end

Maya is wiring up the Insights service so her team can run agents against it. She opens Repositories, clicks New, and names it Insights API; the identifier fills in as insights-api as she types. She picks the team's GitHub provider from the dropdown, which already shows a green Connected as @maya, pastes https://github.com/orcette/insights.git into the Git URL, leaves the default branch blank so it follows main, and sets a clone depth of 1 because nobody's agent needs the full history to add a CSV button. She tags it insights and analytics and saves.

With the repository now in edit mode, she clicks Test Connection. Green: the credential reached orcette/insights. She turns on a weekly documentation health review with a seven-day lookback, leaves auto-apply off for now, and she is done. The next time someone on her team runs a Flow against the Insights API repository, the sandbox clones it shallow from main with Maya's provider credential, and the agent goes to work. Nobody has to think about the connection again until something about the code's home actually changes.

Why connecting works this way

The instinct, when a tool wants to work with your code, is to give it your code: grant it a token with broad reach, let it pull the repository down, trust that it puts things back. Disco Parrot connects to a repository the other way around. It holds a pointer and a credential reference, not your source; it clones fresh into a disposable sandbox at run time and throws the clone away after; and it confirms the credential can reach the repository with the exact command the sandbox will use, so the connection you set up is the connection that runs. The usual bargain is access for convenience; this one gives you the convenience without the access ever changing hands.

For a planner, connecting a repository is a one-time setup that turns the Insights service from a name into something an agent can actually work in, and after that the connection is invisible. For an engineer, the branch and clone depth are the same knobs they would set on a clone by hand, and Test Connection answers the question they would otherwise discover the hard way: can this credential reach this repository. For a lead, the set of code agents can reach is a curated list an admin owns, not something that accretes one engineer's side-repo at a time, so the answer to "what can agents touch here" is a page you can read, not an audit you have to run. For the person who has to sign off on connecting a code host at all, the answer is that nothing about connecting moves the boundary they are paid to defend: connecting adds a route, not a copy, the source never leaves GitHub, the working clone dies with its sandbox, and the credential that reaches it stays with the provider and is never handed to the agent. There is no new place your code lives and no key the agent gets to keep.