Repos
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). 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
Section titled “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, then This project, then Repos, with the agent repo registration 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.
Add repos
Section titled “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
Section titled “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
Section titled “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 explains the policy.
Merging when branches must be up to date
Section titled “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
Section titled “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. 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
Section titled “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 for how several land in order.
Remove a repo
Section titled “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
Section titled “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, then This project, then 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 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.
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 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.
- Worktrees: where an agent does a ticket’s work.
- Branching and CI: how By Dawn names branches and where they open.
- Repo bootstrap: set new repos up the same way every time.
- Pick up results from GitHub Actions: let By Dawn read a GitHub repo’s test results.