GitHub Projects Sync

Bidirectional GitHub Projects v2 sync.

7 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

github.status

GET

Report whether the GitHub App is configured (server env) and connected (installed) for this workspace. Returns an install URL when not yet connected.

• AI tool: github_status
• API: GET /api/invoke/github.status

Input

No parameters.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

github.resolve_project

POST

Preview a GitHub Project v2 by URL (github.com/orgs|users//projects/) — returns its fields, single-select options (incl. Status), and item count WITHOUT importing. Call this first when a user pastes a GitHub Project URL.

When the agent calls it: Use FIRST when a user wants to import a GitHub project. If connectionOk is false, tell them to install the GitHub App via the returned installUrl (or the Integrations page).

• AI tool: github_resolve_project
• API: POST /api/invoke/github.resolve_project

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "connectionId": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ]
}

github.import_project

POST · mutating

Import a GitHub Project v2 as a synced local project + table view. Creates project_fields mirroring the GitHub fields (Status single-select → a local Status select + ticket statuses), label definitions with colors, and one ticket (kind=imported) per project item. Only manually-imported projects sync.

When the agent calls it: Call after resolve_project once the user confirms. Routes the user to the new project afterward.

• AI tool: github_import_project
• API: POST /api/invoke/github.import_project

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "projectName": {
      "type": "string"
    },
    "createView": {
      "type": "boolean"
    },
    "connectionId": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ]
}

github.sync_pull

POST · mutating

Re-pull the latest from a bound GitHub project into the local view. Idempotent — dedupes on the external id, updates changed items, tombstones removed ones.

• AI tool: github_sync_pull
• API: POST /api/invoke/github.sync_pull

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bindingId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "bindingId"
  ]
}

github.sync_push

POST · mutating

Force-push local changes (status / labels / custom fields) to GitHub for a bound project. Normally unnecessary — edits push automatically on save. Pass ticketId to push a single item.

• AI tool: github_sync_push
• API: POST /api/invoke/github.sync_push

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bindingId": {
      "type": "string",
      "minLength": 1
    },
    "ticketId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "bindingId"
  ]
}

github.list_bindings

GET

List GitHub project bindings for the workspace, optionally filtered to one local project.

• AI tool: github_list_bindings
• API: GET /api/invoke/github.list_bindings

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1
    }
  }
}

github.unbind

POST · mutating

Stop syncing a GitHub binding. keepLocalData=true (default) leaves the imported tickets/view frozen in place; false soft-deletes the container project too.

• AI tool: github_unbind
• API: POST /api/invoke/github.unbind

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bindingId": {
      "type": "string",
      "minLength": 1
    },
    "keepLocalData": {
      "type": "boolean"
    }
  },
  "required": [
    "bindingId"
  ]
}