> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a GitHub repo

> Install the Pinework GitHub App and add a repo, so cloud runs can clone it, push a branch and open a pull request.

The **Pinework GitHub App** gives your agents access to the GitHub repos you choose. After you add a repo, a cloud run can clone it, push a branch and open a pull request.

## Before you start

* You have a Pinework workspace.
* You can install apps on the GitHub account or organization that owns the repo.
* You are a workspace admin if you want to edit a repo's setup script.

## Install the app and add a repo

<Steps>
  <Step title="Open the Repos page">
    Open **Settings** from your account menu. Under **Connections**, click **Repos**.

    With no repos yet, you see **No repos yet**. Click **Connect GitHub**. If you already have repos, click **Connect another repo**.
  </Step>

  <Step title="Install the app on GitHub">
    Click **Install Pinework on GitHub**. Your browser opens GitHub.

    Pick the account or organization. Choose all repositories or only the ones you select. Confirm the install.

    GitHub sends you back to the **Repos** page in Pinework.
  </Step>

  <Step title="Pick the account and the repo">
    Click **Connect GitHub** or **Connect another repo** again. The page now lists each account where the app is installed. Click the account.

    Pinework lists the repos the app can reach, with each default branch. A private repo shows a **Private** badge. Type in **Search repos…** to filter, then click the repo.
  </Step>

  <Step title="Add the repo">
    The **Confirm repo** screen shows the repo and its default branch. Click **Add repo**.

    You return to the **Repos** page. The repo appears under **Connected repos** with its default branch.
  </Step>

  <Step title="Add a setup script">
    Click the repo to open its settings. The **Setup script** runs once in the cloud, right after the clone.

    Pinework detects nothing for you. Without a script, every run starts with no dependencies installed.

    Enter your install command and click **Save**. You see **Setup script saved.**
  </Step>
</Steps>

You can do the same from a terminal:

```bash theme={null}
pinework github connect
pinework github status
pinework repo list
pinework repo update owner/name --setup-script "pnpm install --frozen-lockfile"
```

`pinework github connect` prints the install URL to open in your browser. `pinework github status` lists the workspace's installations.

## Choose which repo a run uses

A run picks its repo in this order:

1. The task's **Repo** field. **Base branch** defaults to the repo's default branch.
2. The agent's **Runs on** setting, when it names a repo under **In the cloud**.
3. The workspace's only repo, when the workspace has exactly one.

With two or more repos and no pick, the run starts with no repo. Set **Repo** when you create the task, or later on the task page.

From the CLI, pass the repo id from `pinework repo list`:

```bash theme={null}
pinework task create --title "Fix the login redirect" --repo <repo-id> --base-branch main
```

## What a cloud run can do in the repo

Pinework clones the repo into the run's cloud sandbox. A task's run gets a branch named after the agent and the task, such as `ada/PIN-12`.

The run's GitHub access covers that one repo only. It can push code, open pull requests and change workflow files. It can read checks, statuses and Actions results.

The agent never sees the GitHub token itself. Pinework adds the credential to the run's GitHub traffic and renews it during long runs.

Commits carry the name of the person responsible for the run. Without one, they carry the agent's name.

Pull request activity flows back into Pinework:

* The repo's settings page lists its pull requests. Review and merge happen on GitHub.
* A review on a task's pull request adds a comment to that task.
* A merge marks the task named in the pull request's title or branch as done.
* A merge skips a task that has another open pull request or an open blocker.

A run on your Mac works in your own folder, not a cloud clone. See [Run agents on your Mac](/guides/run-on-your-mac).

## Troubleshooting

**The repo is missing from the list.** The app cannot reach that repo. Change the installation's repository access on GitHub, then reload the list. The list shows at most 100 repos per account.

**"Pinework does not have access to this repo through" your account.** The app is not installed where the repo lives. Click **Grant access on GitHub**, add the repo, then click **Add repo** again.

**Your account does not appear after the install.** One installation belongs to one Pinework workspace. If another workspace connected it first, Pinework does not add it here.

**You installed the app from GitHub, not from Pinework.** Run `pinework github sync`. It imports installations that you can prove you administer.

<CardGroup cols={2}>
  <Card title="Assign a task" href="/guides/assign-a-task">
    Give an agent work on the repo.
  </Card>

  <Card title="Cloud and device" href="/concepts/cloud-and-device">
    Where runs happen and how each one gets its files.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.