GitHub Integration Module

GitHub integration workflow module for the Loopstack automation framework.

Provides ConnectGitHubWorkflow, a guided multi-step workflow that takes a workspace from “not connected” to “pushed to GitHub”. It composes OAuth authentication, repo creation/linking, remote configuration, and branch divergence resolution into a single reusable workflow with human-in-the-loop decision points.

When to Use

• You need a one-click “Connect to GitHub” experience that handles OAuth, repo setup, and push in a single workflow.
• You want to embed GitHub onboarding into a larger workflow by calling ConnectGitHubWorkflow as a sub-workflow.
• You need guided divergence resolution when connecting to a repo that already has commits.
• Use @loopstack/github instead if you only need individual GitHub API tools (repos, issues, PRs, actions) without the guided connection flow.

Installation

npm install @loopstack/github-integration @loopstack/github @loopstack/git @loopstack/hitl @loopstack/oauth @loopstack/remote-client

Register the module:

import { Module } from '@nestjs/common';
import { GitHubIntegrationModule } from '@loopstack/github-integration';

@Module({
  imports: [GitHubIntegrationModule],
})
export class AppModule {}

GitHubIntegrationModule imports GitModule, GitHubModule, HitlModule, and OAuthModule internally. You do not need to import those yourself, but their packages must be installed.

A GitHub OAuth app must be configured in your OAuth provider setup (client ID and secret). See the @loopstack/oauth and @loopstack/github docs for details.

Quick Start

Inject ConnectGitHubWorkflow into your own workflow and run it as a sub-workflow:

import { z } from 'zod';
import { BaseWorkflow, Transition, type TransitionInput, Workflow } from '@loopstack/common';
import { ConnectGitHubWorkflow } from '@loopstack/github-integration';

@Workflow({
  title: 'Setup Project',
  description: 'Initialises a project and connects it to GitHub.',
  schema: z.object({}).strict(),
})
export class SetupProjectWorkflow extends BaseWorkflow {
  constructor(private readonly connectGitHub: ConnectGitHubWorkflow) {
    super();
  }

  @Transition({ to: 'awaiting_github' })
  async start(state: Record<string, never>) {
    await this.connectGitHub.run(
      {},
      { callback: { transition: 'onGitHubConnected' }, show: 'inline', label: 'Connect to GitHub' },
    );
  }

  @Transition({ from: 'awaiting_github', to: 'end', wait: true })
  async onGitHubConnected(state: Record<string, never>, input: TransitionInput) {
    this.setResult({ github: input.data });
  }
}

How It Works

ConnectGitHubWorkflow is a state-machine workflow that orchestrates multiple sub-workflows and tools:

start
  │
  ▼
check_auth ──[needs auth]──► awaiting_auth ──[callback]──► check_auth
  │
  ▼
awaiting_choice ──[callback]──► route_choice
  │                                │
  │              ┌─────────────────┼─────────────────┐
  │              ▼                                   ▼
  │         createRepo (wait)                  repoSelected (wait)
  │              │                                   │
  │              └─────────────────┬─────────────────┘
  │                                ▼
  │                        configure_remote
  │                                │
  │                                ▼
  │                       check_uncommitted
  │                         │            │
  │              [clean]────┘            └────[dirty]
  │                 │                          │
  │                 ▼                          ▼
  │            setup_remote         awaiting_commit_confirm
  │                 │                          │
  │                 │              [callback]───┘
  │                 │                 │
  │                 └────────┬───────┘
  │                          ▼
  │                   check_divergence
  │                     │          │
  │         [can push]──┘          └──[diverged]
  │              │                        │
  │              ▼                        ▼
  │             done              awaiting_sync_choice
  │              │                        │
  │              │            [callback]───┘
  │              │                 │
  │              └────────┬───────┘
  │                       ▼
  │                      done
  │                       │
  │                       ▼
  │                      end

Step-by-step

1. Check auth – calls GitHubGetAuthenticatedUserTool to see if the user already has a valid token.
2. OAuth – if not authenticated, launches OAuthWorkflow with provider: 'github' and scopes: ['repo', 'user']. The sign-in UI is embedded in the parent’s run view via the default show: 'inline'.
3. Repo choice – uses AskUserWorkflow (HITL) to let the user choose between creating a new repo or connecting an existing one.
4. Create or select – either calls GitHubCreateRepoTool or GitHubListReposTool followed by a second HITL prompt to pick from the list.
5. Uncommitted changes – checks GitStatusTool for uncommitted work. If dirty, asks the user whether to auto-commit or cancel.
6. Remote setup – configures the git remote URL via GitRemoteConfigureTool, sets the user identity via GitConfigUserTool, and fetches remote refs.
7. Divergence resolution – for a linked repo, compares the checked-out branch with the same branch on origin. If the workspace is ahead, or the remote does not have that branch yet, it is pushed directly. If the remote is ahead or the histories differ, asks the user to choose: pull, merge, force-push, or cancel. A detached HEAD or a failing git command fails the run.
8. Push – calls GitPushTool to finalize the connection.
9. Result – saves a MarkdownDocument summarizing the outcome and dispatches a git.updated workspace event.

Return value

On success:

{ "repo": "user/repo-name", "url": "https://github.com/user/repo-name" }

On cancellation:

{ "cancelled": true }

Args Reference

ConnectGitHubWorkflow takes no arguments (empty object schema):

Arg	Type	Required	Description
(none)	–	–	The workflow requires no input args. OAuth and repo details are collected interactively.

Configuration

No module-level configuration. OAuth credentials are managed by @loopstack/oauth and the GitHub OAuth provider from @loopstack/github.

Public API

• Module: GitHubIntegrationModule
• Workflow: ConnectGitHubWorkflow

Dependencies

Package	Role
@loopstack/common	Framework types, decorators (@Workflow, @Transition, @Guard), documents (MarkdownDocument)
@loopstack/core	ClientMessageService for dispatching workspace events
@loopstack/git	Git tools: GitStatusTool, GitPushTool, GitFetchTool, GitRemoteConfigureTool, GitConfigUserTool
@loopstack/github	GitHub API tools: GitHubGetAuthenticatedUserTool, GitHubCreateRepoTool, GitHubListReposTool
@loopstack/hitl	AskUserWorkflow for interactive decision points
@loopstack/oauth	OAuthWorkflow and OAuthTokenStore for GitHub authentication
@loopstack/remote-client	BashTool for running git commands on the remote server
zod	Schema validation

Related

• @loopstack/github – low-level GitHub API tools (repos, issues, PRs, actions, search) used by this workflow
• @loopstack/git – git tools for commit, push, pull, branch, and remote operations
• @loopstack/oauth – provider-agnostic OAuth framework; required for the GitHub OAuth flow
• @loopstack/hitl – human-in-the-loop workflows used for interactive prompts
• Workflows – how to build and compose workflows in Loopstack
• Sub-workflows – pattern for calling one workflow from another with callbacks

About

Author: Jakob Klippel

License: MIT