Repositories and git
Connect GitHub repositories to your organization, add them to a workspace, highlight and extract code, and commit, push and open pull requests as yourself.
Yard works with GitHub repositories in two steps. A repository is connected to your organization once; after that you add it to a workspace's canvas, and remove it from there, like any other block. The workspace reads a repository from a read-only reference copy. Changes happen in projects, each on its own branch, and go back to GitHub as commits and pull requests made by you.
Before you start
Two connections are needed, and Yard asks for each when it is missing:
- The Yard GitHub App, once per organization. An organization admin installs it under Settings, Repositories, on the GitHub account that owns the repositories. It decides which repositories Yard may see. The admin's own GitHub account must be able to see the installation: one that belongs to someone else's account is refused ("not yours").
- Your own GitHub account, once per person. Under Account settings, GitHub,
choose Connect GitHub, or Use a token instead to paste a
personal access token that can read and write contents and pull requests
(and workflows, to push changes to files under
.github/workflows/).
You see only repositories that are both in the organization's installation
and visible to your own GitHub account. Pushes, pull requests and merges
always use your own connection, and commits carry your GitHub name and email,
so work on GitHub is attributed to you. Without a connection those actions
are refused. A push that adds or changes a GitHub Actions workflow
(.github/workflows/) also needs the App's Workflows permission; when it
is missing, Yard says so and names the file. If Yard can no longer use your
connection, it says it "needs to be renewed" with a Reconnect button.
Connecting a repository
A repository is connected to the organization, under Settings, Repositories: pick it from what your GitHub account can see, or create a new one. Every workspace of the organization can then add it to its canvases. An admin disconnects it there too, once no workspace shows it and no project works in it; Yard says which workspace still has it.
Reading a file at a branch or worktree
Under Resources, the Repos folder lists the repositories, each with the branch the workspace reads. Hovering one shows its branch, open pull requests and last push to its default branch. Clicking it opens its page on Overview: its open pull requests, its recent pushes to the default branch, its open issues and its branches, each with a tab of its own (Pull requests, Branches, Issues, Pushes to main), and Files for its tree. Every pull request, branch, issue and push there is a context item: drag it into the context box, onto a project, a doc or the composer, pin it, or use its buttons. A file opens in a tab, read only. The picker at its top right reads it at another branch or in a project's worktree.
Select lines and a menu offers Ask, Start a project from this, Attach to a project or your context and Copy a reference. Its chip is the selection: drag it onto a chat, a tab, the context box or a project in the sidebar. Selected text in a doc offers the same.
Adding a repository to a canvas
Choose Add in a canvas's toolbar, then Repository. Search the list and pick a repository to place it on the canvas. The list is what the organization has connected. Connect a repository… connects another one from your GitHub account without leaving the canvas, and Create repository makes a new private repository on GitHub, connects it and adds it.
There is nothing to set up in the workspace in between: Yard fetches its copy when the block is added.
Removing a repository from a canvas
Delete its block. The repository stays connected to the organization, so it can be added again, here or on another canvas. When no canvas or doc of the workspace shows it any more (its block or a code excerpt of it), Yard removes the workspace's copy a few seconds later; Undo brings the block back, and the copy with it. The copy stays for as long as a project still works in the repository.
The repository block says three things at a glance:
- The workspace's main branch of it, with the commit it is at and when it
was last fetched. When that is not the repository's default branch on
GitHub, a line under it says so: "Main branch here. GitHub's default is
main." - The projects working in a worktree of it, under "N projects" and "merge into" the main branch: each with its pull request number and its changes. Click one to open that project.
- Four buttons: New project (the Write spec dialog with the repository as context), Pull requests and Branches (each with its count once known, see below) and Explore files.
A block made taller also lists its top-level files. Everything else is in
its ⋯ menu (see below). It always says what is true now, without
reloading the page:
- Cloning… or Fetching… while the runner copies or updates it.
- The runner is offline., with since when, while the workspace's runner is away.
- If the last copy or update failed, why, when it happened and when it was last tried (for example "4m ago, checked just now").
A failure is not the last word. When the runner comes back, Yard tries the
repository again, and it keeps trying every few minutes while the runner is
online. The error goes away as soon as an attempt works. yard repo list
in a terminal reports the same status as the block.
The copy follows its branch. Where the Yard GitHub App is installed, a push updates it straight away; otherwise it is fetched every couple of minutes while the block is on screen. The block's files, its code excerpts and the explorer change with it.
The block's menu
The ⋯ button in the block's header, or a right-click on the block, opens
its menu:
- This canvas (the workspace's copy of the repository): Main branch (with the branch), Mark as read-only or Allow edits, and Refresh test baseline (with how old the baseline is, and how many tests fail on it).
- On GitHub: Projects merge into (with the main branch; shown here, set with Main branch) and Open on GitHub.
- Then Ask the agent, Comment, Link to project and Show on sheet, and last Remove from canvas…, which asks first.
Choosing the main branch
Each workspace keeps a main branch for every repository it has. It starts as
the repository's default branch on GitHub, and can be any other branch, for
example develop or release/2.4 when that is where work is based.
Main branch in the block's menu lists the repository's branches,
newest first with the default branch on top, each with its last commit and
tags: default, PR #n for a branch with an open pull request, and in a project for a branch a project works on. Pick another branch and it is the
main branch from now on: the block's files, its code excerpts and the
explorer all follow, new projects start from it, and their pull requests go
into it (also those opened with Open PR in the Git view). Follow-up
projects an agent creates with yard project create start from it too.
Someone who can only view the canvas cannot change it.
Projects that already exist keep the branch they started from: their pull requests still go there.
Pull requests and branches
The repository block's Pull requests and Branches buttons each open a window you can move and resize, listing the repository's open pull requests (author, target branch, whether it has conflicts, how its checks went) or its branches.
Every row has New project from this. Pick what the project is for: Work on it, Fix conflicts, Fix review comments / CI or Review (a branch offers Work on it and Review). The Write spec dialog opens with the repository block as context and instructions for that intent, which you can change.
The last choice, Only create the branch (on a pull request Only check it out), asks for no task: Create branch makes the project with its worktree on a branch of its own, named after the branch or pull request, and no agent starts. Give it a task later in the project's chat or spec.md.
- A project from a pull request works on the pull request's own branch, so what it pushes updates the pull request. A branch can be checked out in one place only: when another project already works on it, or the workspace reads the repository at it, creating the project is refused and says where it is. Pull requests from forks are listed but cannot start a project, since their branch is not in the repository.
- A project from a branch works on that branch as it is: its commits are in the worktree, and what the project pushes updates it. In the dialog you can switch to a branch of its own that starts there instead. The branch the workspace reads always gets a new branch.
The lists need GitHub access to the repository: your own connection, or the organization's GitHub App.
The branch a project starts from
In the Write spec dialog every repository that gets a new worktree has a branch button: a new branch from the workspace's main branch (the default), a new branch from another one, or an existing branch as it is (see Projects and specs). With no instructions written, Create empty project makes the project with its branches and starts no agent; when exactly one other branch is picked, the project is named after it.
The work composer offers the same choice without
the dialog. With Work chosen, each repository chip (one you added, or a
repository block among the chips) shows where the project starts, new from main by default. Click it for Where the project starts: A new branch
from main, A new branch from another one (the chip then reads new from release/2.4) or An existing branch, as it is, from a searchable list with
each branch's last commit. Under them it says where the pull request goes:
into the branch a new branch starts from when you picked one ("The pull request
goes into release/2.4, the branch it starts from."), otherwise into main,
the main branch. A branch still to be picked holds the project until it is: the
line under the composer says "Pick the branch for …, or go back to a new
branch." With Goal chosen there is no "new branch from another one": a goal
builds on the workspace's branch or on an existing one.
A fourth choice, Read-only reference, makes no branch at all: the project
gets a copy of the repository to read, at main or at a branch you pick from the
same list, with no branch of its own and no pull request in it. The chip then
reads read-only (or read-only at release/2.4), and the popover says "Read
only: the project makes no branch and no pull request in this repository." Any
branch on GitHub can be read, even the workspace's own or one another project
works on. A repository the workspace marks read-only offers only this choice, so
you can still pick the branch it is read at.
With Ask (or Investigate) chosen, each repository chip names the branch
the agent reads, main by default, or the branch the chip came in at (dropped
from a branch row, or named by a doc). Click it for Which branch to read and
pick another from the list: the question is answered from that branch. An Ask
that becomes a project checks its repositories out read-only, at the branch
picked.
A repository added to a project later can start from another branch too:
yard worktree add <repo> --base <branch> in the project's box. A branch that
is not on GitHub is refused, and nothing is created.
A sub-project starts each repository its parent works on from the parent's branch, pushed first, its pull request going into it. It follows that branch: rebased when the parent's branch moves (never while its own agent works; a conflict goes to its agent), and moved onto the main branch, with its pull request, once the parent's merges.
Read-only repositories
A repository that is only there for reference (a design system, another
team's service, a spec repository) can be marked read-only in a workspace:
Mark as read-only in its block's ⋯ menu. A lock and "read-only"
show on the block. From then on:
- New projects only read it. The Write spec dialog shows it as read-only and cannot switch it to a worktree, and repositories the context names are checked out read-only. Its chip in the work composer still picks the branch it is read at.
- No worktree of it is made: adding one from a project (or
yard worktree addin a box) is refused, and a checkout an agent makes by hand is not adopted. - Nothing is written to or pushed from a worktree of it made before it was marked, and automatic pushes and pull requests skip it.
- Agents are told it is a reference that must not be changed.
Allow edits in the same menu undoes it. Fetching still works.
Test baseline
A repository with a test config has a test baseline: the commit it was
taken at and how many tests and type errors fail there. Refresh test
baseline in the block's ⋯ menu shows how old it is and how many fail, and
takes a new one. Agents use it to tell their own failures from the ones already on the
branch: see Test baselines.
Workspace logo
A workspace shows a small logo next to its name in the top bar, the workspace switcher and the list of workspaces; without one it shows its initials. When the first repository is added, the picture of its owner on GitHub becomes the logo. Change it in the workspace settings under General, Logo: From GitHub takes it from one of the workspace's repositories, Upload… takes a picture from your computer, and Remove goes back to the initials. A picture in Files becomes the logo with Use as workspace logo in its menu. Pictures are cropped to a square and made small in the browser before they are saved.
Browsing and highlighting
Choose Explore files on the block, or double-click it, to open the explorer in a panel over the canvas. It has three columns:
- Files: the tree, with a filter. A star on a file highlights it.
- Code: the open file with line numbers. Click a line number to pick it;
Shift+click picks a range. Add an optional Note and press Highlight lines, or Highlight file with no lines picked. - Highlights: every highlight with its note, which you can edit or remove. Click one to jump to it.
Highlights tell agents where to look first. They can still read the whole repository.
Extracting files as blocks
With a file open, press Extract this file, or Extract these lines with lines picked. The code becomes a read-only block beside the repository block, joined to it by a line. Right-clicking a file in the tree offers Extract as code block too, and Add to canvas as a file for a plain file block.
A Markdown file opens rendered, as a page, and a JSON file as a tree. Two tabs in the top right corner of the block, View and Raw, switch between that and the file's text. The choice is kept on the block, so everyone sees the same; someone who can only view the workspace switches for themselves.
The JSON tree folds: click an object or an array to open or close it. Expand all and Collapse all do it for the whole document, and the filter keeps only the keys and values that match what you type. JSON that does not parse, a file too large to read whole, and an excerpt of a few lines of JSON are shown as text.
The Git view
Each project works in a git worktree on its own branch. The Git view, on the project's Changes tab (Git), shows them all: open the Files view and switch to Git, or open a project and choose its Changes tab. Each worktree has a card with its repository, branch, lines added and removed, and one button for the next step:
- Commit while there are uncommitted changes. Write a message and press Commit.
- Push once there are commits GitHub does not have yet.
- Open PR once the branch is pushed.
- Merge while the pull request is open and GitHub can merge it. Yard asks first, then squashes the branch into its base on GitHub, as you.
- Resolve conflicts when the pull request conflicts with its base, and Checking… while GitHub is still working that out.
- Finish or abort the merge… when a merge was left half done.
Under the card's head, a bar shows where the branch stands: ↑ commits
ahead of its base (for example main), ↓ commits behind it, the number
of changed files, and the pull request with whether it can be merged. It
also has the actions that move the branch:
- Fetch asks GitHub what is new. Nothing in the worktree changes; the counts are current afterwards.
- Pull appears when the branch on GitHub has commits you do not have here. It only ever fast-forwards: if both sides have new commits, nothing changes and Yard says so.
- Update from main appears when the branch is behind its base. It merges the base into the branch (Yard never rebases and never force-pushes). If that would conflict, the worktree is left exactly as it was and the conflicting files are listed.
- Migrations numbered twice. When the branch and its base both added a
drizzle migration with the same number (
0042_…sqlon each side), the update does not stop onmeta/_journal.jsonand the snapshots: the base keeps its numbers, the branch's migrations move up after the base's highest, and the journal and snapshots are made again (with the repository'sdrizzle-kit generatewhen it is installed in the worktree, or else by adding the moved entries to the base's journal). The merge is committed without the agent, and the message says what moved. Only when something else conflicts too is the agent asked.
When a pull request conflicts, a card lists the files and offers Resolve with the agent: Yard fetches the base and asks the agent, in your chat, to merge it. The files the request names are read again as it is sent, so they are the ones that conflict then. The agent is asked to read each conflicted file, settle it, run the checks and commit. Nothing is pushed: when the agent is done, Push sends the merge and GitHub looks at the pull request again. A merge that stopped half way can be handed to the agent the same way, or undone with Abort the merge, which puts the worktree back where it was.
To have Yard push, resolve conflicts and merge several finished projects one after the other, queue them for merge (see Projects and specs).
Pushes, opened and merged pull requests and new conflicts are also recorded as lines in the project's chat. A conflict is said once per base commit, in the project's main chat: syncing again or pushing a commit that does not fix it says nothing new (see Chat).
In an agent's turn, git fetch origin works with the Yard GitHub App's access,
which can only read the repositories in the workspace: agents never get your
own GitHub connection, so they cannot push, and they have no gh access to
manage pull requests. Pushes happen from Yard, as you, to the repository's
own address on GitHub; a push from a checkout whose git settings point
elsewhere (insteadOf, a push URL, a proxy) is refused, and fetches go to the
repository's own address too, whatever origin says. A terminal gets the same
read-only access as an agent, never your own connection: git fetch and
gh pr view work, and yard git push pushes the project's branches as you,
through Yard. The token is only in that process's environment, never in a
file. What an agent asks Yard to do on GitHub (fetch, add a checkout, create a
project or a goal's branch) uses the GitHub App, never your connection.
A project's Changes tab also lets you change which repositories it has. A
read-only checkout has Make writable, which puts it on the project's
branch where it is, keeping what is in it. Under the cards, + owner/repo
adds a worktree of any repository in the workspace that the project does not
have yet. Agents do the same from the project's terminal with
yard worktree add <repo> (see the CLI reference).
A worktree made with plain git worktree add is one Yard does not know about.
With Delete worktrees when done on, a checkout is removed once its pull
request merges, and yard worktree list shows it as removed. The next
message to the project's agent, Start, or yard worktree add <repo> checks it
out again on the project's branch, from the base branch when the old one is
gone.
Beside the card, choose Uncommitted changes, All changes or a single commit to read its diff file by file. Shift-click a second commit to select the commits between them: the files and diffs then show their combined change, from before the oldest to the newest, under a heading such as "3 commits · abc1234..def5678". A plain click selects one commit again. An uncommitted change to one file can be discarded. Viewers, and everyone while the runner is offline, can read diffs but not change anything.
The first few files open by themselves. Lockfiles, minified files and very large changes start closed, so opening the page stays fast. A file with a long diff shows its first 400 lines, with a button for the rest.
Comments on lines
Point at a line of a diff and press the + at its start (or reach it with
Tab) to comment on that line. The comment hangs under the line, as
"Alex Kim on line 43", and everyone with access to the workspace sees it as it
is written; @name tells someone. Under it:
- Send to Claude Code (or whichever agent the project has) posts the comment to the project's chat, quoting the file, the line as it read and what was said, and the agent works on it there. The thread then says "Sent to Claude Code 2m ago" (and who sent it, when it was someone else), and its button reads Send again. Send N comments to … above the files sends every open comment of the repository in one message, leaving out the ones already sent that nobody has written in since; the toolbar says how many those are.
- Answer adds to the thread.
- Resolve marks it done; Reopen brings it back. Answering a resolved thread opens it again.
The agent reads the comments with yard comments list (each with its id, the
line as it read and whether it is outdated) and resolves what it addressed
with yard comments resolve <thread> --note "<what was done>". The thread
then shows Resolved by Claude Code, with the note as the agent's answer,
and the people in the thread are told. The agent can also answer without
resolving (yard comments reply). See the
CLI reference.
A file's head counts its open comments. When the line a comment is on no longer reads as it did (the agent changed it, or the change was reverted), the comment is listed under the file as Outdated, with the line as it read. Comments belong to the project; viewers read them but cannot write.
Revert this change
Each block of changes (a hunk, "Lines 41 to 47") has Revert this change. After you confirm, Yard takes just that hunk back out of the project's worktree. Nothing is committed. On Uncommitted the change is simply gone (it was never committed, so it cannot be brought back). On a commit's diff, or Branch, that part of the commit is undone in the worktree as an uncommitted change: commit it, or discard it to bring the change back. If the file no longer has the change as shown (the diff moved on since you loaded it), nothing changes, Yard says so, and the diff is read again. It needs runner 0.52 or newer; an older runner says to update it.
The chevron before a repository's name collapses its card. A collapsed card keeps its name, branch and number of changed files, and Yard reads nothing from git for it until you expand it again. The browser remembers which cards you collapsed, per workspace, project and repository.
The Git panel
Git in the bottom bar opens a panel under the work with every project worktree in the workspace (on a phone it is in the bar's … menu, and fills the screen). Each row has View diff, which opens that project's Changes tab, or Open PR when a finished project's branch is pushed but has no pull request yet.
A commit linked from a project's chat or work opens its diff over that pane, without leaving the page (see what opens in place).
For the full path from spec to merged pull request, see projects and specs.