Connect GitHub to Windshift

What the integration gives you

The connection lives in your Windshift instance and calls the provider API directly.

• Link repositories: Discover the repositories the connection can reach, then link the ones a workspace tracks.
• Connect changes to work items: Link pull requests or merge requests to the work item, and read item keys from branch names and commit messages.
• Start from a work item: Create a branch and open a change request without leaving the item.
• Follow review threads: Read review comments so a teammate or an agent can continue from the discussion.
• Track releases: Attach a tag to a milestone and see which changes shipped with it.
• Stay current: Webhooks update linked repositories after each push or review event, with polling as a fallback.
• Sync GitHub Issues: Import GitHub Issues as Windshift work items, and push status changes and comments back to the issue.

Ways to connect

Windshift connects to github.com with an OAuth App, an access token, or a GitHub App. Repository discovery, branches, commits, pull requests, reviews, releases, and webhooks run through the GitHub REST API.

Windshift creates branches and change requests, so the connection needs write access, not only read access.

• OAuth App: Each user authorizes their own GitHub account. Windshift stores a per-user token, so activity is attributed to the person who connected.
• Access token: One personal access token covers all operations. Use a dedicated account for server-to-server work.
• GitHub App: Install the app on an organization and grant fine-grained permissions. Windshift discovers the installations the app can reach.

Set up the integration

A Windshift administrator configures the provider once. Workspace administrators then link repositories.

Keep the credentials with the team that owns the Git host. Rotate the token or secret on the same schedule as your other service accounts.

• Create the credentials in GitHub: Register an OAuth App, create a personal access token, or create and install a GitHub App. For OAuth and Apps, set the callback URL that Windshift shows in Settings, SCM Providers.
• Add the provider in Windshift: Open Settings, SCM Providers, add a provider, choose GitHub and the authentication method, then paste the credentials and save.
• Connect a workspace: In the workspace, open Settings, Source control, connect the GitHub provider, and link the repositories the workspace tracks.
• Confirm the webhook: Windshift registers a repository webhook when the connection allows it. Verify the delivery in the repository settings on GitHub.

Permissions and scopes

Exact permission names follow the provider. Check them against your instance policy before you grant access.

• Link and browse repositories: The token owner or app installation can access the repository.
• Create branches, pull requests, and reviews: Repository write access, or a GitHub App with contents and pull request write permissions.
• Register the repository webhook: Repository admin access, or a GitHub App with webhook administration permission.
• OAuth scope: repo read:user user:email

Frequently asked questions

Can I connect more than one GitHub organization?

Yes. Add a provider for each organization or GitHub App installation, then link the repositories each workspace needs.

Which GitHub authentication method should I choose?

Use an OAuth App when each person should act with their own account, a GitHub App for fine-grained organization permissions, and an access token for a single service account.

Can I restrict a provider to specific workspaces?

Yes. A system administrator can restrict a provider to an allowlist of workspaces.