GitHub Integration

The GitHub integration connects your GitHub repositories to SetGet projects. Once connected, issues, pull requests, comments, labels, and states sync bidirectionally between the two platforms. Your development team works in GitHub while your project managers, designers, and stakeholders work in SetGet -- and both sides see the same data.

What you get

• Bidirectional issue sync -- create an issue in GitHub and it appears as a work item in SetGet; create a work item in SetGet and it appears as an issue in GitHub.
• Pull request linking -- reference a SetGet work item identifier in a PR title or body and the PR is automatically linked to that work item.
• Comment sync -- comments posted on a GitHub issue appear on the linked SetGet work item, and vice versa.
• Label sync -- labels applied in GitHub propagate to SetGet and labels applied in SetGet propagate to GitHub.
• State mapping -- define how GitHub issue states (open/closed) map to SetGet workflow states (Backlog, In Progress, Done, etc.).

Prerequisites

Before you begin, ensure:

• You have a GitHub account with admin access to the organization whose repositories you want to connect.
• You have Admin or Owner role in your SetGet workspace.
• The repositories you want to link are not archived.

Setup steps

Step 1 -- Connect your GitHub organization

1. In SetGet, go to Settings > Integrations.
2. Find the GitHub card and click Connect.
3. SetGet redirects you to GitHub's OAuth authorization page.
4. Select the GitHub organization you want to connect.
5. Choose whether to grant access to all repositories or selected repositories.
6. Click Authorize.
7. You are redirected back to SetGet. The GitHub card now shows a green "Connected" badge with your organization name.

TIP

If your organization requires admin approval for OAuth apps, you may need an organization owner to approve the SetGet app from GitHub's "Third-party access" settings before the connection completes.

Step 2 -- Link a repository to a project

1. Open the SetGet project you want to link.
2. Go to Project Settings > Integrations > GitHub.
3. Click Link Repository.
4. Select the repository from the dropdown. Only repositories the connected account has access to are shown.
5. Click Save.

You can link multiple repositories to the same project, or link one repository to multiple projects.

Step 3 -- Configure state mapping

State mapping defines how GitHub issue states translate to SetGet workflow states and vice versa.

GitHub state	Default SetGet state	Changeable
open	Backlog	Yes
closed	Done	Yes
closed as not planned	Cancelled	Yes

To customize:

1. In the repository link settings, expand State Mapping.
2. For each GitHub state, select the corresponding SetGet state from the dropdown.
3. Click Save Mapping.

WARNING

Changing state mappings affects future syncs only. Existing work items are not retroactively updated.

Step 4 -- Configure label sync

By default, all labels are synced bidirectionally. You can adjust this behavior:

Mode	Behavior
Bidirectional (default)	Labels sync both ways. Creating a label on either side creates it on the other.
GitHub to SetGet only	Labels are imported from GitHub but changes in SetGet are not pushed back.
SetGet to GitHub only	Labels are pushed to GitHub but changes in GitHub are not pulled.
Disabled	No label sync. Labels are managed independently on each side.

Step 5 -- Enable comment sync

Comment sync is enabled by default when you link a repository. To disable it:

1. In the repository link settings, toggle Sync Comments off.
2. Click Save.

When enabled, comments include an attribution line showing the original author and platform.

Bidirectional issue sync

How it works

When a new issue is created in a linked GitHub repository:

1. SetGet receives a webhook event from GitHub.
2. A new work item is created in the linked SetGet project.
3. The work item title, description, labels, and assignee are populated from the GitHub issue.
4. The work item state is set according to the state mapping.
5. A link between the GitHub issue and the SetGet work item is stored.

When a new work item is created in SetGet with GitHub sync enabled:

1. SetGet creates a corresponding issue in the linked GitHub repository.
2. The issue title, description, and labels are populated from the work item.
3. The issue state is set according to the reverse state mapping.
4. A link between the two is stored.

What syncs

Field	GitHub to SetGet	SetGet to GitHub
Title	Yes	Yes
Description / Body	Yes	Yes
State (open/closed)	Yes (via mapping)	Yes (via mapping)
Labels	Yes (if enabled)	Yes (if enabled)
Assignees	Yes (matched by email)	Yes (matched by email)
Comments	Yes (if enabled)	Yes (if enabled)
Milestones	No	No
Reactions	No	No

Assignee matching

Assignees are matched by email address. If a GitHub user's email matches a SetGet workspace member's email, the assignee is mapped automatically. If no match is found, the assignee field is left empty and a note is added to the work item activity log.

Pull request linking

Reference a SetGet work item identifier anywhere in a pull request title, body, or branch name to link it automatically.

Supported formats

Format	Example
Project prefix + number	PROJ-123
Full URL	https://app.setget.io/workspace/project/work-items/PROJ-123

When a PR is linked:

• The work item's Links section shows the PR with its title, status (open, merged, closed), and a direct link to GitHub.
• Merging the PR can optionally transition the work item to a configured state (e.g., "Done").

Auto-transition on merge

To automatically move a work item when a linked PR is merged:

1. In the repository link settings, enable Auto-transition on merge.
2. Select the target state (e.g., "Done" or "In Review").
3. Click Save.

Webhook events

The GitHub integration uses the following webhook events from GitHub:

Event	Purpose
issues	Sync issue creation, updates, state changes
issue_comment	Sync comments
pull_request	Link PRs, detect merges
label	Sync label creation, updates, deletion

SetGet automatically manages the webhook configuration on the GitHub repository. You do not need to create webhooks manually.

Managing the integration

View sync status

Go to Project Settings > Integrations > GitHub to see:

• Last sync timestamp
• Number of linked work items
• Recent sync errors (if any)

Pause sync

You can pause syncing without disconnecting:

1. In the repository link settings, toggle Pause Sync.
2. While paused, no new events are processed. Events that occur during the pause are not retroactively synced when you resume.

Unlink a repository

1. Go to Project Settings > Integrations > GitHub.
2. Click the Unlink button next to the repository.
3. Confirm the action.

Unlinking stops all syncing for that repository. Existing work items and GitHub issues are not deleted.

Disconnect GitHub

To completely remove the GitHub integration:

1. Go to Settings > Integrations > GitHub.
2. Click Disconnect.
3. Confirm the action.

This revokes the OAuth token and removes all repository links. Existing data is preserved.

Troubleshooting

Problem	Cause	Solution
No repositories appear in the dropdown	OAuth scope is too narrow	Reconnect and grant access to the desired repositories
Issues are not syncing	Webhook was deleted on GitHub	Disconnect and reconnect the integration
Assignees are not mapping	Email mismatch	Ensure GitHub and SetGet accounts use the same email
Comments appear as "SetGet Bot"	Expected behavior	Synced comments are posted by the integration app
State mapping seems wrong	Custom mapping needed	Review and update the state mapping table
PR links are not detected	Wrong identifier format	Use the PROJ-123 format in the PR title or body
OAuth approval pending	Org requires admin approval	Ask an org owner to approve the SetGet app on GitHub

TIP

If sync issues persist after re-authorizing, check GitHub's webhook delivery log at Repository > Settings > Webhooks > Recent Deliveries to see if GitHub is successfully sending events.

Security considerations

• The OAuth token is stored encrypted on the SetGet backend. It is never sent to the frontend.
• SetGet requests the minimum OAuth scopes necessary: repo, read:org, and write:repo_hook.
• Webhook payloads from GitHub are verified using HMAC-SHA256 signatures before processing.
• You can revoke the OAuth token at any time from GitHub's Settings > Applications > Authorized OAuth Apps.

Related pages

• Integrations overview
• GitLab integration
• Import from GitHub
• Webhooks
• Workflow states