# GitHub

Polyscope integrates with GitHub through the `gh` CLI to work with issues, pull requests, and CI checks directly from the app.

## Prerequisites

Make sure the [GitHub CLI](https://cli.github.com/) (`gh`) is installed and authenticated:

```bash
gh auth login
```

If your repository uses SSH remotes and you're seeing "Permission denied (publickey)" errors, see [SSH Authentication](/docs/troubleshooting/ssh-authentication) for how to resolve this.

## Creating Workspaces from Issues

One of the most powerful features is creating workspaces directly from GitHub issues. This gives the agent full context about what needs to be done.

### Fetching Issues

Click the **GitHub** icon on a repository in the sidebar to fetch open issues. Polyscope runs `gh issue list` to retrieve them.

You can search issues dynamically by typing in the issue picker — Polyscope queries GitHub server-side so you can find issues across large repositories.

### Creating the Workspace

Select an issue from the list to create a workspace linked to it. The workspace will:

- Store the issue number, title, and URL
- Show the issue reference in the workspace header (e.g., "Issue #123: Fix login bug")
- Include the issue context when the agent starts working
- Optionally close the issue when the workspace is merged

![Workspace created from a GitHub issue](/images/docs/issue-from-github.png)

## Creating Workspaces from Pull Requests

You can also create workspaces from existing pull requests — useful for reviewing, iterating on, or fixing CI failures on open PRs.

Select a PR from the GitHub panel to create a workspace that checks out the PR's branch.

## Merge and PR Workflows

When a workspace is ready to ship, Polyscope offers two paths:

### Creating a Pull Request

Click the **PR** button in the workspace header. The agent will:

1. Commit any uncommitted changes
2. Push the workspace branch to the remote
3. Create a PR using `gh pr create`
4. Store the PR URL in the workspace header for quick access

You can also create a **draft PR** using the dropdown on the merge button — useful for getting CI feedback before the work is ready for review.

Once a PR exists, the button changes to **Push to PR**, so subsequent changes go to the same pull request.

<!-- ![Pull request created from workspace](/images/docs/TODO.png) -->

### Merging Directly

Click **Merge** to merge changes directly into your base branch. The agent will stage, commit, push, and update the remote. If the workspace was created from a GitHub issue, the merge flow can automatically close the linked issue.

### Custom Prompts

You can customize merge and PR behavior per repository in [repository settings](/docs/core-concepts/repositories):

- **Merge Prompt** — Custom instructions for the merge flow (e.g., "Run tests before merging" or "Use conventional commit format")
- **PR Prompt** — Custom instructions for PR creation (e.g., "Include a test plan" or "Add the `needs-review` label")

## CI Monitoring

When a workspace has a pull request, Polyscope monitors GitHub Actions check runs and shows their status in the activity feed:

- **In progress** — A check is currently running
- **Passed** — The check completed successfully
- **Failed** — The check failed (click to see details on GitHub)
- **Skipped** — The check was skipped

### Auto-Fix

When a CI check fails, Polyscope can automatically prompt the agent to fix the issue. The agent reads the failure details and attempts to resolve it — then pushes the fix so CI runs again.