Repositories and git

Yard works with GitHub repositories. A workspace keeps a read-only reference copy of each repository you add. 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 from Settings → Repositories on the GitHub account that owns the repositories. It decides which repositories Yard may see.
2. Your own GitHub account, once per person. Go to Account → GitHub and choose Connect GitHub, or Use a token instead to paste a personal access token that can read and write contents and pull requests.

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. If Yard can no longer use your connection, it says it "needs to be renewed" with a Reconnect button.

Adding a repository

Choose Add → Repository in the canvas toolbar. Search the list and pick a repository to place it on the canvas. Connect a repository… adds one from your GitHub account to the organization, and Create repository makes a new private repository on GitHub and adds it.

The repository block shows its name, its branch and its files once the copy is ready. If the copy fails, the block says why.

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.

Choosing the branch

The branch on the repository block is a dropdown. Pick another branch and the workspace reads that one from now on: the block's files, its code excerpts and the explorer all follow, and new projects start from it and open their pull requests against it. It cannot be changed while the canvas is read-only.

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 Create spec dialog shows it as read-only and cannot switch it to a worktree, and repositories the context names are checked out read-only.
• 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.

Workspace logo

A workspace shows a small logo next to its name in the header, 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 under Settings → 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 shows them all: open the Files view and switch to Git, or open a project and choose its Git 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.

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, 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.

Pushes, opened and merged pull requests and new conflicts are also recorded as lines in the project's chat (see Chat).

In an agent's turn and in a project's terminal, git fetch origin and gh (for example gh pr view) work with your GitHub connection. The token is only in that process's environment, never in a file.

A project's Git 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.

Beside the card, choose Uncommitted changes, All changes or a single commit to read its diff file by file. 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 Git panel

Git in the footer opens a panel with every project worktree in the workspace. Each row has View diff, which opens that project's Git tab, or Open PR when a finished project's branch is pushed but has no pull request yet.

For the full path from spec to merged pull request, see projects and specs.