GitHub Integration Guide
Connect PlanningForge to GitHub to import issues directly into your planning sessions.
Table of Contents
Integration Overview
PlanningForge's GitHub integration allows you to import issues directly from your GitHub repositories into planning poker sessions. Estimate your backlog items with your team without leaving PlanningForge.
What You Can Do
- Import issues from any GitHub repository you have access to
- Filter issues by state, labels, milestone, and assignee
- Run planning poker sessions with imported issues
- View issue details and links during estimation
- Track which issues have been estimated
Requirements
- A GitHub.com account
- Access to the repositories you want to import from
- Team Owner or Admin role in PlanningForge
- The repository must have issues enabled
Read-Only Integration
The GitHub integration is currently read-only. PlanningForge can import issues but does not write data back to GitHub. Your story point estimates are stored in PlanningForge only.
Setting Up the Integration
Prerequisites
Required Permissions
- PlanningForge: Team Owner, Scrum Master, or Product Owner role
- GitHub: Read access to the repositories you want to connect
Access Integration Settings
- Navigate to your team dashboard in PlanningForge
- Click on the Settings tab
- Scroll down to the GitHub Integration section
- Click Configure GitHub
Connecting to GitHub
GitHub App Installation
Minimal Permissions
PlanningForge uses a GitHub App with minimal permissions. We only request read-only access to issues and metadata - we cannot read your code, make changes to your repository, or access any other data.
Step 1: Start the Installation
- From the GitHub integration settings page, click Install GitHub App
- You'll be redirected to GitHub's app installation page
Step 2: Install PlanningForge App
- Log into your GitHub account if prompted
- Choose where to install the app:
- Your personal account - For personal repositories
- An organization - For organization repositories (requires admin access)
- Select which repositories to grant access to:
- All repositories - Access to all current and future repositories
- Only select repositories - Choose specific repositories (recommended)
- Review the permissions (read-only access to issues and metadata)
- Click Install to complete the installation
Step 3: Select a Repository
- After installing, you'll be redirected back to PlanningForge
- A list of repositories you granted access to will be displayed
- Select the repository you want to connect to this team
- Click Save Repository
Connection Complete
Once connected, you'll see the repository name displayed in your team settings. You can now import issues from this repository into your planning sessions.
Importing Issues
Starting an Import
- Open an existing planning session or create a new one
- Click the Import from GitHub button
- The import modal will open showing your connected repository
- Use the filters to narrow down the issues you want to import
- Click Load Issues to fetch matching issues
- Select the issues you want to import
- Click Import Selected
Filter Options
State
Filter issues by their current state:
- Open - Issues that are currently open (default)
- Closed - Issues that have been closed
- All - Both open and closed issues
Milestone
Filter issues by their assigned milestone:
- All milestones - Show issues from any milestone
- No milestone - Only issues without a milestone
- Specific milestone - Issues assigned to a particular milestone
Assignee
Filter issues by who they're assigned to:
- All assignees - Show issues assigned to anyone
- Unassigned - Only issues without an assignee
- Specific person - Issues assigned to a particular user
Labels
Filter issues by their labels:
- Select one or more labels to filter by
- Issues must have all selected labels to match
- Labels are displayed with their GitHub colors
Max Results
Limit the number of issues loaded:
- 10, 30, 50, or 100 issues
- Most recently updated issues are shown first
Selecting Issues
After loading issues, you can select which ones to import:
- Click individual issues to select or deselect them
- Use Select All to select all loaded issues
- Use Select None to clear your selection
- The number of selected issues is shown at the bottom of the modal
What Gets Imported
- Issue title becomes the story title
- Issue body becomes the story description (first 500 characters)
- Issue number is linked to the story for easy reference
- Labels, milestone, and assignee are displayed but not stored
Planning with GitHub Issues
Issue Display During Voting
When voting on imported GitHub issues, you'll see:
- GitHub badge - A visual indicator showing this story came from GitHub
- Issue number - Displayed as "#123" with a link to the original issue
- Story title - The issue title from GitHub
- Description - The issue body (truncated if long)
Viewing Original Issues
Click the GitHub issue link to view the full issue on GitHub:
- See the complete issue description and all comments
- View attachments, linked pull requests, and related issues
- Check the full discussion history
- The link opens in a new tab so you don't lose your place
Tip: Use Issue Details
Encourage team members to click through to the original GitHub issue when they need more context. The issue comments often contain valuable discussion that helps with estimation.
Managing Your Connection
Changing the Repository
You can change the connected repository without disconnecting:
- Go to your team's GitHub integration settings
- Click Change Repository
- Select a different repository from the list
- Click Save
Note
Changing the repository doesn't affect stories that were already imported. Those stories retain their original GitHub issue links.
Testing the Connection
Verify your GitHub connection is working:
- Go to your team's GitHub integration settings
- Click Test Connection
- A success message will show your GitHub username and repository count
Disconnecting
To remove the GitHub integration:
- Go to your team's GitHub integration settings
- Click Disconnect
- Confirm the disconnection
What Happens When You Disconnect
- The connection between this team and GitHub is removed
- You won't be able to import new issues until you reconnect
- Previously imported stories are not affected
- GitHub issue links on existing stories will still work
GitHub App Remains Installed
Disconnecting from PlanningForge does not uninstall the GitHub App from your GitHub account. To fully remove the app, go to GitHub Settings → Applications → Installed GitHub Apps and uninstall it there.
Troubleshooting
Connection Issues
"Connection failed" when testing
- The GitHub App may have been uninstalled from your account
- Try disconnecting and reinstalling the GitHub App
- Check that your GitHub account is still active
"Invalid state" error during installation
- The installation link may have expired (valid for 10 minutes)
- Try starting the installation process again
- Clear your browser cookies and retry
Can't see my repositories
- You may not have granted the GitHub App access to those repositories during installation
- Go to GitHub Settings → Applications → Installed GitHub Apps
- Click Configure next to PlanningForge to add more repositories
- Organization repositories require admin access to install the app
"Resource not accessible" error
- The GitHub App doesn't have access to the selected repository
- Update your installation to include this repository in GitHub settings
Import Issues
No issues appear when loading
- Check your filter settings - they may be too restrictive
- Make sure the repository has issues enabled
- Verify you have permission to view issues in this repository
- Try selecting "All" for state instead of "Open"
Import fails with an error
- The GitHub App may have been uninstalled or lost access to this repository
- The repository may have been deleted or made inaccessible
- Try refreshing the page and importing again
- Check your GitHub App installation settings
- Contact support if the issue persists
Issue description is truncated
- This is expected - descriptions are limited to 500 characters
- Click the GitHub issue link to see the full description
Rate Limiting
Getting rate limit errors
- GitHub Apps have generous rate limits, but they can still be exceeded with heavy usage
- Wait a few minutes and try again
- If you're importing many issues, try importing in smaller batches
Need More Help?
If you're experiencing issues not covered here, please contact our support team with details about what you're seeing.