Skip to content

Commit 1008ce8

Browse files
AngelmmiguelAngelmmiguel
authored
feat: add the github issues guide (#34)
1 parent eb35520 commit 1008ce8

1 file changed

Lines changed: 186 additions & 0 deletions

File tree

‎src/content/docs/rover/guides/github-issues.mdx‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: Work on GitHub issues
3+
description: Create tasks directly from GitHub issues and track their relationship throughout the development cycle
4+
sidebar:
5+
order: 3
6+
---
7+
8+
import StepList from '../../../../components/StepList.svelte';
9+
import StepItem from '../../../../components/StepItem.svelte';
10+
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
11+
12+
Rover integrates with GitHub to create [tasks](/rover/concepts/task) directly from issues. This allows you to assign GitHub issues to local AI coding agents and maintain a clear link between the issue and the task result.
13+
14+
## Prerequisites
15+
16+
To create Rover [tasks](/rover/concepts/task) from GitHub issues, you need either:
17+
18+
- **GitHub CLI (`gh`)**: Recommended for private repositories and GitHub Enterprise. Install from [cli.github.com](https://cli.github.com/).
19+
- **Public repository access**: For public repositories, Rover can fetch issues directly from the GitHub API without authentication.
20+
21+
## Create a task from an issue
22+
23+
Use the `--from-github` flag to create a task using the content of a GitHub issue as the task description.
24+
25+
<StepList title="Creating a task from GitHub">
26+
<StepItem step={1}>
27+
Navigate to your project directory
28+
29+
```sh
30+
cd ~/my-project
31+
```
32+
</StepItem>
33+
<StepItem step={2}>
34+
Create a task from a GitHub issue by specifying the issue number
35+
36+
```sh
37+
rover task --from-github 42
38+
```
39+
40+
Rover fetches the issue title and body from GitHub and uses them as the task description.
41+
</StepItem>
42+
<StepItem step={3}>
43+
Follow the task progress
44+
45+
```sh
46+
rover logs -f 1
47+
```
48+
</StepItem>
49+
<StepItem step={4}>
50+
Once the task completes, merge the changes into your branch or push them to a remote branch
51+
52+
```sh
53+
rover merge 1
54+
# or
55+
rover push 1
56+
```
57+
58+
See [Merge changes from tasks](/rover/guides/merge-tasks) for detailed guidance on reviewing and integrating task results.
59+
</StepItem>
60+
</StepList>
61+
62+
:::tip
63+
You can combine `--from-github` with other task options like `--agent` or `--source-branch`:
64+
65+
```sh
66+
rover task --from-github 42 --agent claude:opus --source-branch develop
67+
```
68+
:::
69+
70+
## Understanding GitHub metadata
71+
72+
When you create a task from a GitHub issue, Rover stores metadata about the source issue. This metadata includes:
73+
74+
| Field | Description |
75+
|-------|-------------|
76+
| `type` | Source type, always `github` for GitHub issues |
77+
| `id` | The issue number |
78+
| `url` | Direct link to the GitHub issue |
79+
| `ref` | Reference data including `owner`, `repo`, and `number` |
80+
81+
This metadata maintains the connection between your task and its originating issue throughout the development cycle.
82+
83+
## Inspect GitHub metadata
84+
85+
Use the `rover inspect` command to view the GitHub issue linked to a task.
86+
87+
<StepList title="Viewing GitHub metadata">
88+
<StepItem step={1}>
89+
Inspect a task to see its details, including the linked GitHub issue
90+
91+
```sh
92+
rover inspect 1
93+
```
94+
95+
The output includes a "GitHub Issue" field with a direct link to the original issue:
96+
97+
```
98+
Details
99+
-------
100+
· ID: 1 (a1b2c3d4-5678-90ab-cdef-1234567890ab)
101+
· Title: Implement user authentication
102+
· Status: Completed
103+
· Workflow: swe
104+
· Created At: 1/27/2026, 10:30:00 AM
105+
· GitHub Issue: https://github.com/acme/webapp/issues/42
106+
· Completed At: 1/27/2026, 11:15:00 AM
107+
108+
Workspace
109+
---------
110+
· Branch Name: rover/task-1-xK9mPq2wLz4N
111+
· Git Workspace path: ~/.rover/data/projects/acme-webapp-8f3a1b2c/workspaces/1
112+
```
113+
</StepItem>
114+
<StepItem step={2}>
115+
For programmatic access, use the `--json` flag to get the full source metadata
116+
117+
```sh
118+
rover inspect 1 --json
119+
```
120+
121+
The JSON output includes the complete `source` object:
122+
123+
```json
124+
{
125+
"success": true,
126+
"id": 1,
127+
"title": "Implement user authentication",
128+
"status": "COMPLETED",
129+
"branchName": "rover/task-1-xK9mPq2wLz4N",
130+
"source": {
131+
"type": "github",
132+
"id": "42",
133+
"url": "https://github.com/acme/webapp/issues/42",
134+
"ref": {
135+
"owner": "acme",
136+
"repo": "webapp",
137+
"number": 42
138+
}
139+
}
140+
}
141+
```
142+
</StepItem>
143+
</StepList>
144+
145+
## Working with custom workflows
146+
147+
When using a [custom workflow](/rover/concepts/workflow#custom-workflows) that requires additional inputs beyond a description, Rover extracts the required information from the GitHub issue body. The AI agent analyzes the issue content and maps it to the workflow inputs.
148+
149+
For example, if your workflow requires `description` and `acceptance_criteria` inputs, include both in your GitHub issue body:
150+
151+
```markdown
152+
## Description
153+
Add a login form with email and password fields.
154+
155+
## Acceptance Criteria
156+
- Email validation
157+
- Password minimum 8 characters
158+
- Show error messages on invalid input
159+
```
160+
161+
Rover parses the issue and populates the workflow inputs accordingly.
162+
163+
## Best practices
164+
165+
To get the best results when creating tasks from GitHub issues:
166+
167+
- **Write detailed issue descriptions**: Include context, requirements, and acceptance criteria
168+
- **Use clear formatting**: Markdown headings and bullet points help the agent understand the structure
169+
- **Reference specific files**: Mention file paths or function names when relevant
170+
- **Include examples**: Provide code snippets or expected output when applicable
171+
- **Keep scope focused**: Smaller, well-defined issues lead to better implementations
172+
173+
## Relevant Concepts
174+
175+
<CardGrid>
176+
<LinkCard title="Task" href="/rover/concepts/task" description="Learn about Rover tasks and how they work" />
177+
<LinkCard title="Workflow" href="/rover/concepts/workflow" description="Discover how workflows guide coding agents" />
178+
</CardGrid>
179+
180+
## Related Guides
181+
182+
<CardGrid>
183+
<LinkCard title="Implement a new feature" href="/rover/guides/assign-tasks" description="Create and assign tasks to AI coding agents" />
184+
<LinkCard title="Iterate on tasks" href="/rover/guides/iterate-tasks" description="Refine and improve task implementations" />
185+
<LinkCard title="Merge changes from tasks" href="/rover/guides/merge-tasks" description="Integrate completed tasks into your codebase" />
186+
</CardGrid>

0 commit comments

Comments
 (0)