Overview

The GitHub integration brings code activity, pull request context, and delivery metrics into Sizemotion so that reviews, 1:1s, and OKR check-ins have the full engineering story. Use the Integrations Hub (/integration/manage) to view all available connectors, see status badges, and launch the GitHub configuration flow.

Why it matters

Teams get visibility into work that lives outside the HR system:

  • Syncs repositories, pull requests, and release activity to correlate code with human conversations.
  • Surfaces metrics such as cycle time and review coverage to help managers coach engineers effectively.
  • Enables notifications, alerts, and reports in Sizemotion without asking teammates to toggle between systems.

Sync capabilities

  • Repository discovery: Fetches repos from user and organization scopes so you see both personal and shared projects.
  • Pull request tracking: Imports open/merged PRs, approvals, and reviewers to explain delivery cadence.
  • Release & commit mapping: Records tagged releases and summary commit messages as reference points in your reviews.
  • Webhook support: Optional webhooks keep data fresh between scheduled pulls.

Setup steps

Only account admins can finish the setup. The flow is protected by the IntegrationManagementController and enforces CSRF protection.

  1. Open the Integrations Hub: Visit /integration/manage and click the GitHub card. The hub shows whether the connector is active and summarizes recent sync health.
  2. Create a personal access token: In GitHub, go to https://github.com/settings/tokens and generate a token with the following scopes: repo, admin:repo_hook, read:org, and user:email. Keep the token in a secure vault; we only show it once.
  3. Configure in Sizemotion: Head to the admin-only route /integration/github/config. Paste the token, select the account/organization, and toggle webhook delivery if desired. The controller will validate the scopes before saving.
  4. Set up webhooks (optional): If you need near real-time updates, copy the webhook URL shown on the config page and add it to your GitHub repository settings. Store the webhook secret in Sizemotion under the same page so we can verify payloads.

Permissions & security

Respect the principle of least privilege.

  • Only admin users can access /integration/github/config or POST configuration changes.
  • The token is encrypted at rest, but you should rotate it when the person who created it leaves or when GitHub prompts for rotation.
  • Webhook secrets are stored per-account and signed on every payload to protect against replay attacks.
  • Audit logs show who enabled, disabled, or reconfigured the integration in case you need to trace changes.

Workflow & metrics

Once configured, the integration polls GitHub every 15 minutes and you can always trigger a manual refresh from the hub.

  • Overview data: Use the /integration/github page to browse synced repositories, review pull request status, and see the last sync time.
  • Metrics: Visit /integration/github/metrics for cycle time, review latency, and merge velocity graphs. These metrics feed into one-on-one talking points and retrospective prep.
  • Alerts: Sizemotion highlights when syncs fail, tokens expire, or webhooks reject payloads so you can fix them before data stalls.

Monitoring & health

The Integrations Hub surfaces additional signals:

  • Status badges for every connector (green = active, amber = attention needed, gray = disabled).
  • Quick actions to jump straight into config or view the detail page.
  • Error summaries when API responses fail (e.g., rate limit hits or invalid credentials) so your admin knows the exact call that failed.

Troubleshooting

  • "Route [api.github.overview] not defined" – Use the hard-coded paths /api/github/overview and /api/github/metrics; the tests remind us not to rely on named routes.
  • "Attempt to read property 'id' on null" – Ensure the admin user has a personal team (withPersonalTeam()) so the integration controller can resolve the current account.
  • Missing token errors – The GitHub API returns 401 when there is no token; re-enter a valid personal access token on the config page.
  • Disabled integration – If the hub shows “disabled,” re-enable it in /integration/manage/github or refresh the token/configuration entry.

Frequently Asked Questions

Can I limit the repos the integration sees?

The connector only uses the scopes you grant. Use GitHub team permissions and organization visibility to control which repos your token can read.

What if my token expires?

Simply generate a new token in GitHub, then paste it again on the config screen. Sizemotion will re-validate the token before saving.

How can I see review and merge data for a single team member?

The overview page groups data by repo and PR, but you can filter in the UI and then share a summary link with stakeholders. Use the review candiate list to jump to any engineer’s contributions.

Next steps