Yard Docs
Sign in
On this page

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.

Updated November 11, 2026 · 22 min read

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:

  1. 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").
  2. 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 add in 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.

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_…sql on each side), the update does not stop on meta/_journal.json and 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's drizzle-kit generate when 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.

Was this page useful?
Edit this page