Our GitHub integration lets you create and link GitHub issues from your Harvestr Discoveries. You can then follow the evolution of these issues and their status in GitHub without leaving Harvestr, and let a GitHub Projects board update your Discovery states automatically.
Prerequisites
To use our GitHub integration, you need a Harvestr Editor account, on any paid plan (Core, Scale, or Elite), and a GitHub account allowed to install apps on your organization. If you aren't, GitHub lets you ask an organization owner to approve the installation.
How to connect Harvestr to GitHub
Click Install GitHub App.
In GitHub, pick the organization or account that owns your repositories, then choose which repositories Harvestr can see.
Confirm. You're taken back to Harvestr, and the account appears in the Account card.
Issues on several GitHub organizations? Click Connect another account and repeat for each of them. Harvestr only works with the accounts where the app is installed.
Always start the installation from Harvestr: an installation started directly from GitHub isn't connected to your workspace.
Already connected with the older GitHub connection?
If the Account card shows Legacy OAuth account, everything keeps working as it is. We recommend moving to the GitHub App: you choose exactly which repositories Harvestr can see, and you no longer need to maintain an organization webhook.
To move, click Install GitHub App in the Account card. Your linked issues and automation rules are kept.
Once you've moved, Harvestr only syncs the accounts where the app is installed. If your issues or boards live in several organizations, install it on each one with Connect another account.
How to use the GitHub integration in Harvestr
Now that the integration is set up, a GitHub section appears in every Discovery in Harvestr.
You can now:
create and link one or more new GitHub issues to a Discovery
link one or more existing GitHub issues to a Discovery
1. Create and link new GitHub issues to a Discovery
Once you've decided to take a Discovery to development, you can create issues in GitHub that correspond to what needs to be built.
When you click Create issue in a Discovery, a window opens where you can enter the issue's details: Organization, Repository, Project, Title, Assignee, Labels, Milestone and Description.
Once created, the issue appears in GitHub with the details you entered and a link back to the Discovery in Harvestr. This gives your software team access to the valuable content in your Discovery, such as user feedback.
In your Discovery, you'll also see a link to the newly created issue and be able to track its status as it changes in GitHub.
2. Link existing GitHub issues to a Discovery
Sometimes you'll want to link GitHub issues that already exist to a Harvestr Discovery.
Click the Link issue button in your Discovery. This opens a search bar where you can search a GitHub issue by its name or its key. Searching by key only works when you type the complete key.
3. Track GitHub issue progress from Harvestr
Once you've linked the issue to your Discovery, you can follow its status from the linked Discovery.
You can view issue statuses from your Discovery table by displaying the GitHub issues field.
You can also filter Discoveries based on the properties of linked GitHub issues to track development work easily.
Update Discovery states from a GitHub Projects board
When someone moves an issue on a GitHub Projects board, Harvestr can move the linked Discovery to the state of your choice.
This sync is one way, from GitHub to Harvestr. Changing a Discovery state in Harvestr never moves the card in GitHub.
Create your automation rules
In Settings > Integrations > GitHub, in the Discovery automations card, click New rule. A New rule window opens:
When is filled in for you: A linked GitHub issue is updated.
Under If, next to Project field is, pick a project board, then a field option. Pick the board first: its fields and options load from GitHub.
Under Then, pick the Harvestr state next to Set discovery state to.
Click Create rule. You can have up to 35 rules. Each rule has an on/off switch, and its ⋯ menu lets you Edit, Duplicate or Delete it.
A typical set of rules: In progress moves the Discovery to In development, and Done moves it to Shipped.
On the older GitHub connection: install the webhook
With the GitHub App, there's nothing to install: rules work right away. On a Legacy OAuth account, they only run once an organization webhook is in place.
The Organization webhook card gives you a Payload URL to copy, and a Signing secret field to fill in. In GitHub, open your organization's Settings > Webhooks > Add webhook, then:
paste the payload URL,
set the content type to application/json,
choose a signing secret and paste it,
under Let me select individual events, tick Projects v2 items only,
keep Active ticked and save.
Back in Harvestr, paste the same secret in Signing secret and click Save. A green 200 under Recent Deliveries in GitHub confirms that the URL and the secret are right.
Only an owner of your GitHub organization can create an organization webhook. If that's not you, send them the payload URL and the signing secret.
One webhook per Harvestr project. If the same GitHub organization is connected to two Harvestr projects, each one needs its own payload URL and secret.
Harvestr cannot see, test or remove this webhook. It stays in place when you disconnect GitHub, so delete it yourself in GitHub if you no longer need it.
What you see in a Discovery
A linked issue now shows one tag per board it sits on, in the form Board name: Option, so you can read an issue's position without opening GitHub. The tag updates live when the card moves.
Disconnect GitHub
In Settings > Integrations > GitHub, click ⋯ on the account row, then Disconnect, and confirm. Harvestr stops reading and updating that account's issues and boards. Linked issues stay on their Discoveries.
If GitHub refuses Harvestr's access, the account shows Access lost. Click Reinstall to resume. On a Legacy OAuth account, use ⋯ > Reconnect instead.
Good to know
Existing linked issues can take up to 24 hours before the sync starts working. Harvestr needs one daily pass to recognize issues linked before this feature shipped. New links work immediately.
Only setting or changing a field value triggers a rule. Adding a card to a board without a status, archiving it, or clearing its value changes nothing in Harvestr.
Use a board that belongs to your organization. GitHub only sends these events for organization boards, so a rule built on a personal board never fires.
Rules follow renames, not deletions. Renaming a board, a field or an option is safe. Deleting an option that a rule points to silently stops that rule, and nothing in the interface flags it.
One issue linked to several Discoveries updates them all.
GitHub Projects classic is not supported, only the current Projects boards.
Only Editors and Owners can change the connection and the rules.
FAQ & troubleshooting
My rule never fires
Check, in order: the GitHub App is installed on the organization that owns the board (or, on a Legacy OAuth account, the webhook shows a green 200 in GitHub), the board belongs to your organization, the issue was linked more than 24 hours ago or has been re-linked since, and somebody actually changed the field value rather than just adding the card to the board.
I don't see my GitHub organization in the list when linking an issue
With the GitHub App, click Connect another account in Settings > Integrations > GitHub and install the app on the missing organization.
On a Legacy OAuth account, click ⋯ > Reconnect on the account row, and grant the missing organization in GitHub's authorization window. If it still doesn't show, set the missing GitHub organization as public at the user level in GitHub, for the GitHub user who set up the Harvestr integration.
If you have requests or ideas about how we could improve our GitHub integration to better suit your workflow, send us a message!