name: github description: "GitHub and Git workflow helpers, Issues and Projects v2 management via gh CLI; triggers on 'github', 'create issue', 'list issues', 'github project', 'project board', 'sync tasks', 'create pr', 'pr checks', 'retrigger tests', 'bump version', 'push'."

Purpose

Model-neutral helper for GitHub and Git workflows including Issues, Projects v2, PR management, CI triggers, and version bumping. Uses the gh CLI.

Triggers

Use when the user says:

"create a github issue", "create issue", "new issue"
"list github issues", "show issues", "open issues"
"close issue", "reopen issue", "assign issue"
"github project", "project board", "kanban"
"add to project", "update project field", "move to column"
"sync tasks with github", "import github issues", "export tasks to github"
"create a pr", "check pr status", "retrigger tests", "toggle test label", "pr checks", "bump version", "push to remote"

Configuration

Uses existing gh CLI authentication. Verify with:

gh auth status

Alternatively, set GITHUB_TOKEN environment variable for CI/headless environments.

How to use

Issues

List Issues

# List open issues
lisa github issues list --repo owner/repo
 
# List with filters
lisa github issues list --repo owner/repo --state open --labels bug,urgent --assignee @me --limit 20
 
# List all issues (including closed)
lisa github issues list --repo owner/repo --state all

Create Issue

# Basic issue
lisa github issues create --repo owner/repo --title "Bug: Login fails"
 
# With body and labels
lisa github issues create --repo owner/repo --title "Feature: Dark mode" --body "Add dark mode support" --labels enhancement,ui
 
# With assignee
lisa github issues create --repo owner/repo --title "Task" --assignee username

View Issue

lisa github issues view --repo owner/repo 123

Close/Reopen Issue

# Close as completed
lisa github issues close --repo owner/repo 123
 
# Close as not planned
lisa github issues close --repo owner/repo 123 --reason not_planned
 
# Reopen
lisa github issues reopen --repo owner/repo 123

Assign Issue

lisa github issues assign --repo owner/repo 123 --to username
lisa github issues assign --repo owner/repo 123 --to user1,user2

Label Issue

# Add labels
lisa github issues label --repo owner/repo 123 --add bug,priority-high
 
# Remove labels
lisa github issues label --repo owner/repo 123 --remove wontfix
 
# Add and remove
lisa github issues label --repo owner/repo 123 --add in-progress --remove backlog

Projects v2

List Projects

lisa github projects list --repo owner/repo
lisa github projects list --repo owner/repo --limit 10

View Project

lisa github projects view --repo owner/repo 1

List Project Items

lisa github projects items --repo owner/repo 1
lisa github projects items --repo owner/repo 1 --limit 50

List Project Fields

# Get available fields and their options (useful for set-field)
lisa github projects fields --repo owner/repo 1

Add Issue to Project

# Add issue #123 to project #1
lisa github projects add --repo owner/repo 1 123

Update Project Field

# Set status field (e.g., move to "In Progress" column)
lisa github projects set-field --repo owner/repo 1 ITEM_ID --field Status --value "In Progress"
 
# Set priority
lisa github projects set-field --repo owner/repo 1 ITEM_ID --field Priority --value "High"

Note: Use projects fields to get valid field names and options, and projects items to get item IDs.

Sync (Bidirectional Task Sync)

Sync Lisa tasks with GitHub Issues. Supports import, export, or bidirectional sync.

Import GitHub Issues as Lisa Tasks

# Import all open issues from repo
lisa github sync --repo owner/repo --import
 
# Import issues with specific labels
lisa github sync --repo owner/repo --import --labels task,feature
 
# Preview import without making changes
lisa github sync --repo owner/repo --import --dry-run
 
# Specify group ID for Lisa tasks (default: owner-repo)
lisa github sync --repo owner/repo --import --group my-project

Export Lisa Tasks to GitHub Issues

# Export unlinked tasks as new GitHub issues
lisa github sync --repo owner/repo --export
 
# Preview export
lisa github sync --repo owner/repo --export --dry-run

Bidirectional Sync

# Full two-way sync (import + export + status updates)
lisa github sync --repo owner/repo
 
# Preview all changes
lisa github sync --repo owner/repo --dry-run

Status Mapping

Lisa Status	GitHub State	GitHub Labels
`ready`/`todo`	open	(none)
`in-progress`	open	`in-progress`
`blocked`	open	`blocked`
`done`	closed	(none)

Conflict Resolution: When both Lisa and GitHub have changes, last-write-wins based on timestamps.

I/O Contract (examples)

Create Issue

{
  "status": "ok",
  "action": "create",
  "issue": {
    "number": 123,
    "url": "https://github.com/owner/repo/issues/123",
    "title": "Bug: Login fails"
  }
}

List Issues

{
  "status": "ok",
  "action": "list",
  "issues": [
    {
      "number": 123,
      "title": "Bug: Login fails",
      "state": "open",
      "labels": ["bug"],
      "assignees": ["username"],
      "url": "https://github.com/owner/repo/issues/123",
      "createdAt": "2026-01-22T10:00:00Z",
      "updatedAt": "2026-01-22T10:00:00Z"
    }
  ],
  "total": 1
}

View Issue

{
  "status": "ok",
  "action": "view",
  "issue": {
    "number": 123,
    "title": "Bug: Login fails",
    "body": "Steps to reproduce...",
    "state": "open",
    "labels": ["bug"],
    "assignees": ["username"],
    "url": "https://github.com/owner/repo/issues/123",
    "createdAt": "2026-01-22T10:00:00Z",
    "updatedAt": "2026-01-22T10:00:00Z",
    "author": "reporter",
    "milestone": "v1.0"
  }
}

List Projects

{
  "status": "ok",
  "action": "list",
  "projects": [
    {
      "id": "PVT_kwDOABC123",
      "number": 1,
      "title": "Sprint Board",
      "url": "https://github.com/orgs/owner/projects/1",
      "closed": false,
      "shortDescription": "Current sprint tasks"
    }
  ],
  "total": 1
}

Project Items

{
  "status": "ok",
  "action": "items",
  "items": [
    {
      "id": "PVTI_abc123",
      "type": "ISSUE",
      "content": {
        "number": 123,
        "title": "Bug: Login fails",
        "url": "https://github.com/owner/repo/issues/123",
        "state": "OPEN"
      },
      "fieldValues": {
        "Status": "In Progress",
        "Priority": "High"
      }
    }
  ],
  "total": 1
}

Project Fields

{
  "status": "ok",
  "action": "fields",
  "fields": [
    {
      "id": "PVTF_abc123",
      "name": "Status",
      "dataType": "SINGLE_SELECT",
      "options": [
        { "id": "opt_1", "name": "Todo" },
        { "id": "opt_2", "name": "In Progress" },
        { "id": "opt_3", "name": "Done" }
      ]
    },
    {
      "id": "PVTF_def456",
      "name": "Priority",
      "dataType": "SINGLE_SELECT",
      "options": [
        { "id": "opt_a", "name": "Low" },
        { "id": "opt_b", "name": "Medium" },
        { "id": "opt_c", "name": "High" }
      ]
    }
  ]
}

Sync Result

{
  "status": "ok",
  "action": "sync",
  "direction": "bidirectional",
  "dryRun": false,
  "summary": {
    "imported": 3,
    "exported": 2,
    "updated": 1,
    "skipped": 5,
    "conflicts": 1
  },
  "imported": [
    { "title": "Bug: Login fails", "issueNumber": 123, "issueUrl": "https://github.com/owner/repo/issues/123" }
  ],
  "exported": [
    { "title": "Refactor auth module", "taskUuid": "abc123", "issueNumber": 456, "issueUrl": "https://github.com/owner/repo/issues/456" }
  ],
  "updated": [
    { "title": "Update docs", "taskUuid": "def789", "issueNumber": 101, "issueUrl": "https://github.com/owner/repo/issues/101" }
  ],
  "conflicts": [
    {
      "taskUuid": "ghi012",
      "taskTitle": "Fix tests",
      "issueNumber": 102,
      "reason": "Status mismatch: Lisa=\"in-progress\", GitHub=\"closed\"",
      "resolution": "remote",
      "localUpdatedAt": "2026-01-22T10:00:00Z",
      "remoteUpdatedAt": "2026-01-22T11:00:00Z"
    }
  ]
}

Error

{
  "status": "error",
  "error": "Not authenticated. Run: gh auth login"
}

Workflow Examples

Bug Triage Workflow

# 1. Create issue
lisa github issues create --repo owner/repo --title "Bug: Login fails" --labels bug,triage
 
# 2. Add to project board
lisa github projects add --repo owner/repo 1 123
 
# 3. Set initial status
lisa github projects set-field --repo owner/repo 1 ITEM_ID --field Status --value "Triage"
 
# 4. After investigation, update priority and move to backlog
lisa github issues label --repo owner/repo 123 --add priority-high --remove triage
lisa github projects set-field --repo owner/repo 1 ITEM_ID --field Status --value "Backlog"

Sprint Planning Workflow

# List items in backlog
lisa github projects items --repo owner/repo 1 --limit 50
 
# Move selected items to sprint
lisa github projects set-field --repo owner/repo 1 ITEM_ID --field Status --value "Todo"
lisa github issues assign --repo owner/repo 123 --to developer

Task Sync Workflow

# 1. Start of day: Import any new GitHub issues as Lisa tasks
lisa github sync --repo owner/repo --import
 
# 2. Work on tasks in Lisa (status updates tracked automatically)
lisa tasks update "Fix login bug" --status in-progress
 
# 3. End of day: Export new tasks and sync status changes
lisa github sync --repo owner/repo
 
# 4. Check what would sync before running
lisa github sync --repo owner/repo --dry-run

Git Workflows

Check PR Status

# View PR checks
gh pr checks <PR_NUMBER> --repo <owner/repo>
 
# View PR details
gh pr view <PR_NUMBER> --repo <owner/repo>

Retrigger CI Tests

When a PR test fails and a fix is pushed, tests don't automatically re-run. Toggle the "TEST" label to trigger:

# Remove and re-add TEST label to trigger CI
gh pr edit <PR_NUMBER> --repo <owner/repo> --remove-label "TEST"
sleep 2
gh pr edit <PR_NUMBER> --repo <owner/repo> --add-label "TEST"

Check CircleCI Pipeline Status

Prerequisites: Set CIRCLE_TOKEN environment variable, or have CircleCI CLI configured at ~/.circleci/cli.yml.

# Get latest pipeline for a branch
curl -s -H "Circle-Token: ${CIRCLE_TOKEN}" \
  "https://circleci.com/api/v2/project/gh/<owner>/<repo>/pipeline?branch=<BRANCH>" \
  | jq '.items[0] | {number, state, created_at}'
 
# Get workflow status for a pipeline
curl -s -H "Circle-Token: ${CIRCLE_TOKEN}" \
  "https://circleci.com/api/v2/pipeline/<PIPELINE_ID>/workflow" \
  | jq '.items[] | {name, status}'

Poll CI Until Completion

# Poll current branch
lisa pr checks <PR_NUMBER>
 
# Or use gh CLI directly
gh pr checks <PR_NUMBER> --watch

Bump Version

Bump the semantic version in package.json before pushing:

# Bump minor version (default): 1.2.3 → 1.3.0
lisa bump-version
 
# Bump patch version: 1.2.3 → 1.2.4
lisa bump-version patch
 
# Bump major version: 1.2.3 → 2.0.0
lisa bump-version major

Configuration

Control version bumping via LISA_AUTO_BUMP_VERSION in .lisa/.env:

Value	Behavior
`true` (default)	Enabled, defaults to `minor` bump
`false`	Disabled, bump commands are skipped
`patch` / `minor` / `major`	Enabled with that bump type as the default

# In .lisa/.env:
LISA_AUTO_BUMP_VERSION=false        # Disable version bumping
LISA_AUTO_BUMP_VERSION=patch        # Default to patch bumps

A CLI argument always overrides the env default: lisa bump-version major bumps major regardless of the env setting.

Workflow: Push with Version Bump

Bump version (default: minor):
```
lisa bump-version
```

Commit the version bump:

git add package.json
git commit -m "chore: bump version to $(node -p "require('./package.json').version")"

Push to remote:
```
git push
```

Workflow: PR Test Failure

Identify the failure - Check CircleCI logs or GitHub checks
Push a fix - Commit and push the fix to the branch

Retrigger tests - Toggle the TEST label:

gh pr edit <PR_NUMBER> --repo <owner/repo> --remove-label "TEST" && \
sleep 2 && \
gh pr edit <PR_NUMBER> --repo <owner/repo> --add-label "TEST"

Monitor - Watch for the new pipeline to complete

Cross-model checklist

Claude: Use JSON output for parsing; concise instructions
Gemini: Explicit commands; minimal formatting
All models: Always include --repo flag; parse JSON responses

Notes

Requires gh CLI v2.0+ or GITHUB_TOKEN environment variable
Requires CircleCI CLI/token for pipeline status
Projects v2 uses GraphQL API (requires appropriate permissions)
Rate limits apply per GitHub API policies
--repo flag is always required (no auto-detection)
TEST label triggers CI workflow via GitHub Actions/CircleCI integration