Skip to main content
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

1

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

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

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

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

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.
You can do the same from a terminal:
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:

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

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

Assign a task

Give an agent work on the repo.

Cloud and device

Where runs happen and how each one gets its files.