# Repos

> Add the code repositories a project's tickets work in, check By Dawn can reach them, set their branches, and choose which repos each ticket works in.

This page helps you give a project the code its tickets work on. By the end, the project has its repos, By Dawn can
reach each one, and you know how a ticket picks the repos it works in.

A **repo** is a git repository on GitHub, Azure DevOps or any other git host. A project owns as many repos as it
needs, such as a web app, an API and a shared library, and a ticket can work in one of them or several at once.
When an agent starts on a ticket, it clones each repo the ticket works in onto its machine and does the work on a
branch of its own (see [Worktrees](https://docs.bydawn.com/worktrees/)). That's why a coding project needs at least one repo before
you can create tickets: "An agent clones the repo a ticket targets, so a ticket with no repo has nowhere to run."

## Open the Repos page

Press `⌘4`, or open the project menu at the top of the sidebar and choose **Repos**. The same table is
also in **Settings › This project › Repos**, with the [agent repo
registration](#let-agents-add-the-repos-they-create) setting under it.

The page lists every repo in the project with its branches, whether By Dawn can reach it, and what's happening in it:
open pull requests and running workers. A project with six repos or more also gets a filter box ("Filter repos…") and
an access filter, such as **Unverified** or **Problems**.

*[Screenshot: The Repos page with three repos, each showing its remote, branching strategy, Requires up-to-date branches, default and dev branches, and a Private or Public access badge]*

## Add repos

Choose **Add repos**. Anyone in the project can add one. The dialog has a tab for each way in:

- **From GitHub**: pick from the repos your organization has shared with By Dawn's GitHub App. A repo already in the
  project shows as "already in this project". If one is missing, choose **Manage repo access on GitHub** to share it
  with the app, then **Refresh**.
- **From Azure DevOps**: pick from your Azure DevOps organization's repos in the same way.
- **Enter a URL**: paste the repo's **Remote URL** and choose its **Name in SAW**, the name tickets and branches
  show. The name doesn't change anything on the host. Use this for any other git host, or for a GitHub repo before
  GitHub is connected.

Connecting GitHub or Azure DevOps lets By Dawn list your repos and check private ones. Only an org owner or admin can
connect them. If you aren't one, the GitHub tab offers **Get a link for an org owner**: copy the message it gives
you and send it to them. The page updates on its own once they've installed the app.

When you enter a URL, By Dawn checks it as you type:

| What it says | What it means |
| --- | --- |
| "Reachable — public repo" | Anyone can clone it. |
| "Reachable — private repo, verified through GitHub" | By Dawn's GitHub App can see it. |
| "Couldn’t verify — private, or the URL is wrong." | By Dawn can't tell which. **Add it anyway** if you know the URL is right: agents clone with their own git credentials. |
| "SSH remote — can’t check it anonymously." | By Dawn can't check an SSH address. Agents use their own git credentials. |

When a repo has git submodules, By Dawn adds those too, so tickets can work in them.

## Check that By Dawn can reach them

The **Access** column says whether By Dawn can see each repo:

- **Public** or **Private**: verified, the second through the GitHub App.
- **Unverified**: By Dawn couldn't see it. Click it for the likely reason, such as "The GitHub connection couldn’t see this
  repo. It may be outside the connected org or not shared with the app."
- **Unreachable**: the host didn't answer.
- **SSH**: an SSH address, which By Dawn can't check. Agents still clone it with their own credentials.
- **Not checked**: not checked yet. By Dawn checks new repos in the background, or choose **Check**.

**Recheck all** checks every repo again, for example after you've shared repos with the GitHub App. A strip at the
top says when repos aren't shared with the app ("2 repos aren’t shared with the SAW app on GitHub"), with **Manage
repo access** to fix it.

## Set each repo's branches

The **Branches** column has two fields you can edit in place. Press `Enter` or click away to save, and
`Esc` to undo.

- **default**: the branch work starts from and opens back into unless a branching policy says otherwise, usually
  `main`. By Dawn fills it in from the repo when it first checks it, and never overwrites a branch you've set.
- **dev**: the development branch, such as `develop`, if you work in GitFlow. Empty shows as "same as main", and the
  default branch stands in for it.

How tickets name their branches, and which of these two each kind of ticket uses, is set by the branching policy.
The line under each repo's name shows the strategy that applies and where it comes from, such as "GitFlow · inherited
from project". Click it, or choose **Customize branching for this repo…** in the row's **⋯** menu, to set it for this
repo alone. [Branching and CI](https://docs.bydawn.com/branching-and-ci/) explains the policy.

### Merging when branches must be up to date

**Requires up-to-date branches** tells By Dawn whether the repo's main branch only accepts a pull request that's up to
date with it. When it does, By Dawn holds the CI of a pull request that's queued behind another and runs it once the pull
request reaches the front, so CI isn't spent on a merge that's about to change.

- **Auto**: By Dawn decides from what it has seen on that branch in the last 30 days, such as GitHub refusing a merge as
  out of date. The hint says when it last saw that.
- **On** or **Off**: always hold, or never.

## The row menu

Each repo's **⋯** menu has the rest:

- **Recheck access**
- **Customize branching for this repo…**
- **Bootstrap repo…**, for GitHub repos: set the repo up with a ruleset, files, variables and secrets, as your
  policy says. See [Repo bootstrap](https://docs.bydawn.com/repo-bootstrap/). Only project admins can run it.
- **Copy remote URL**, and **Open on GitHub** or **Open on Azure DevOps**
- **Remove from project…**

## Choose which repos a ticket works in

In a project with two repos or more, a ticket's header has a repos chip. **All repos** means the ticket can work in
every repo in the project. Click it and tick the repos this ticket works in ("Repos this ticket works in"), so the
agent only clones and changes those.

A running worker picks up added repos on its next run. You can't untick a repo that already has a pull request on
the ticket ("Has a pull request on this ticket"), so close the pull request first. A ticket keeps at least one repo.

A ticket works on its own branch in each of its repos, and opens a pull request in each one it changes. See
[Pull requests](https://docs.bydawn.com/pull-requests/) for how several land in order.

## Remove a repo

Choose **Remove from project…** in the repo's **⋯** menu. Only org admins can remove a repo, because it changes every
ticket that works in it.

The dialog says how many tickets work in the repo, and whether any workers are running in it right now. Removing it:

- takes it off every ticket. Those tickets keep their other repos, and By Dawn forgets their branch, worktree and pull
  request in this repo.
- doesn't stop a running worker.
- doesn't touch the repo itself: "no branches, PRs, or clones change" on GitHub or wherever it lives.

## Let agents add the repos they create

An agent sometimes needs a new repo, such as for a new service. With **Agents may register repos** on, in
**Settings › This project › Repos**, a worker can add a repo it has created to the project, as long as
By Dawn's GitHub App can already reach it. Each one is recorded on the worker's ticket, and the project's [bootstrap
policy](https://docs.bydawn.com/repo-bootstrap/) is applied straight away. It's off to start with, and only project admins and org admins can
turn it on.

Next to it, **Agents may set org Actions variables** lets a worker create or update GitHub Actions variables at the
organization level, shared only with this project's repos. Every change is recorded on the worker's ticket. It's off
to start with too. See [Actions variables](https://docs.bydawn.com/actions-variables/).

## FAQ

**Do agents need GitHub to be connected to clone a private repo?**

No. Agents clone with the git credentials on their machine. Connecting GitHub lets By Dawn list your repos, check private
ones and open pull requests through its app.

**Can a ticket work in two repos at once?**

Yes. It gets a branch and a [worktree](https://docs.bydawn.com/worktrees/) in each, and a pull request in each it changes.

**Why can't I create a ticket?**

A coding project needs a repo first, because an agent needs somewhere to do the work. Add one, then create the
ticket.

## Next

- [Worktrees](https://docs.bydawn.com/worktrees/): where an agent does a ticket's work.
- [Branching and CI](https://docs.bydawn.com/branching-and-ci/): how By Dawn names branches and where they open.
- [Repo bootstrap](https://docs.bydawn.com/repo-bootstrap/): set new repos up the same way every time.
- [Pick up results from GitHub Actions](https://docs.bydawn.com/tests-github-artifacts/): let By Dawn read a GitHub repo's test results.

Source: https://docs.bydawn.com/repos/