🔗

How to Set Up GitHub

Connect your GitHub account to start creating issues from Slack

ℹ️ Important: Individual Setup Required

Each workspace member must connect their own GitHub account individually. This ensures that issues are created with the proper permissions and attributions.

⚠️ Important: Organization Authorization & SAML

If you are connecting to repositories within a GitHub organization, please review GitHub’s documentation on OAuth Apps and Organizations .

If your organization enforces SAML SSO, you must have an active SAML session before running the /github-setup command.

If the setup fails, visit your GitHub organization in the browser, authenticate to establish an active SAML session, and then retry the /github-setup command.

📋 Prerequisites

  • ✓ Issue Pilot installed: The app must be installed in your Slack workspace
  • ✓ GitHub account: You need a personal or organizational GitHub account
  • ✓ Repository access: You must have write access to the GitHub repositories where you want to create issues

1 Connect Your GitHub Account

Follow these steps to link your GitHub account with Issue Pilot:

  1. Open Slack and navigate to the Issue Pilot app (find it in your Apps section or search for "Issue Pilot")
  2. Open a direct message (DM) with the Issue Pilot app
  3. In the DM, type the slash command:
    /github-setup
  4. Press Enter
  5. Issue Pilot will send you a message in the DM with a button that says "Connect to GitHub"

    💡 Tip: The button appears directly in your DM conversation with Issue Pilot

  6. Click the "Connect to GitHub" button
  7. You'll be redirected to GitHub's authorization page

2 Authorize Issue Pilot on GitHub

On GitHub's authorization page, you'll see the permissions Issue Pilot is requesting:

Requested Permissions:

  • • repo: Full control of private and public repositories

Why this permission?

Issue Pilot needs repository access to:

  • • Create issues in your repositories
  • • Verify you have access to specified repositories
  • • Add issue labels and assignees (future feature)
  1. Review the permissions carefully
  2. If you're part of GitHub organizations, you can choose which organizations to grant access to
  3. Click the green "Authorize [App Name]" button
  4. You may be asked to enter your GitHub password or confirm with 2FA

⚠️ Organization Access: If you want to create issues in organization repositories, make sure to grant access to those organizations during authorization.

3 Confirmation

After successful authorization:

  1. You'll be redirected to a success page showing "✅ GitHub Connected!"
  2. The page will confirm:
    • Your GitHub account is successfully connected
    • Your GitHub username
    • Next steps for configuration
  3. You can close this browser window and return to Slack

🎉 Success! Your GitHub account is now connected to Issue Pilot. You're ready to configure your default repository.

4 Set Your Default Repository

Setting a default repository makes creating issues faster by automatically selecting which repo to use.

To set a default repository:

  1. In any Slack channel, type:
    /github-config owner/repo

    Replace owner and repo with your actual repository details

  2. Examples:
    /github-config octocat/Hello-World
    /github-config mycompany/backend-api
    /github-config username/my-project
  3. Issue Pilot will verify:
    • The repository exists
    • You have access to it
    • You have permission to create issues
  4. If successful, you'll see: "✅ Default repository set to: owner/repo"

💡 Pro Tips:

  • • You can change your default repository anytime by running /github-config again
  • • To see your current default repository, type /github-config without any parameters
  • • You can override the default repository when creating issues (explained in the usage guide)

5 Verify Your Setup

To confirm everything is configured correctly:

  1. Type /github-config (without parameters)
  2. You should see your current default repository displayed
  3. If you see "Not set", run /github-config owner/repo to set one

Quick Test:

To test that everything works:

  1. 1. Navigate to any Slack channel with a conversation
  2. 2. Right-click on a message (or click the three-dot menu)
  3. 3. Look for "Create GitHub Issue" in the shortcuts menu
  4. 4. If you see it, your setup is complete! ✅

🔐 Managing GitHub Access

Viewing Authorized Apps:

  1. Go to GitHub.com and log in
  2. Click your profile picture → Settings
  3. In the left sidebar, click Applications
  4. Click the Authorized OAuth Apps tab
  5. Look for "Issue Pilot" in the list

Granting Additional Organization Access:

  1. From the Authorized OAuth Apps page, click on "Issue Pilot"
  2. Scroll to the Organization access section
  3. Click Grant next to any organization you want to give access to
  4. Organization owners may need to approve the request

Revoking Access:

If you need to disconnect Issue Pilot from GitHub:

  1. Go to the Authorized OAuth Apps page (steps above)
  2. Click on "Issue Pilot"
  3. Click the Revoke button
  4. Confirm the revocation

⚠️ Note: After revoking access, you'll need to run /github-setup again to reconnect.

📚 Working with Multiple Repositories

You can create issues in any repository you have access to, not just your default:

Three Ways to Specify a Repository:

  1. 1. Use your default repository

    Simply use the shortcut without specifying a repo - Issue Pilot uses your configured default

  2. 2. Specify during issue creation

    When using the shortcut, a modal will appear where you can enter a different repository

  3. 3. Change your default

    Run /github-config new-owner/new-repo to update your default

🔧 Troubleshooting

/github-setup command not working?

  • • Make sure Issue Pilot is installed in your workspace
  • • Try typing the command in a different channel
  • • Check if the app is added to the channel (invite it by @mentioning)

Can't access a repository?

  • • Verify you have write access to the repository on GitHub
  • • Check if the repository is in an organization that needs to approve Issue Pilot
  • • Make sure you entered the repository name correctly (owner/repo format)

"Connect to GitHub" button doesn't appear?

  • • The message might have scrolled up - look for Issue Pilot's response after running the command
  • • Try running /github-setup again
  • • Check your Slack message settings to ensure buttons are enabled

Authorization page shows an error?

  • • Clear your browser cache and cookies
  • • Try using a different browser or incognito mode
  • • Make sure you're logged into the correct GitHub account

Still having issues?

Contact our support team at [email protected]

🎯 What's Next?

Now that GitHub is connected, you're ready to start creating issues!

Learn to Use the Shortcut

Discover how to convert Slack conversations into GitHub issues with one click.

View Usage Guide →

Manage Your Subscription

Upgrade your plan for more issues per month and advanced features.

View Billing Guide →