How do I authenticate?

Use gh auth status, or export GITHUB_TOKEN in your environment for CI/headless usage.

How do I target a specific repository?

Always include --repo owner/repo in commands to pin the scope to the desired repository.

github

Scanned

npx machina-cli add skill TonyCasey/lisa/github --openclaw

Files (1)

SKILL.md

13.2 KB

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

Overview

A model-neutral helper for GitHub and Git workflows, covering Issues, Projects v2, PR management, CI triggers, and version bumps using the gh CLI. It streamlines common operations like listing and creating issues, managing projects, syncing tasks, handling PR checks, and bumping versions.

How This Skill Works

The tool uses the gh CLI under the hood to execute repository actions based on user intent expressed in prompts (for example, github issue or project board). It authenticates via gh auth status or a GITHUB_TOKEN and runs gh commands targeted to a specific repository with the --repo flag.

When to Use It

You want to list open issues in a repository.
You need to create, view, or assign issues with labels and assignees.
You manage a Projects v2 board and need to move items or update fields.
You want to sync Lisa tasks with GitHub issues or trigger/verify PR checks.
You need to bump a version or push changes to a remote repository.

Quick Start

Step 1: Authenticate gh (gh auth status or export GITHUB_TOKEN).
Step 2: Choose a scope and repo, e.g., --repo owner/repo, and pick an action (issues, projects, or sync).
Step 3: Run a safe test command like 'lisa github issues list --repo owner/repo' to verify proper targeting.

Best Practices

Verify gh authentication with gh auth status before mutating actions.
Always specify --repo owner/repo to avoid cross-repo changes.
Use filters like --state, --labels, and --assignee to narrow results before acting.
Review PR checks and CI status after triggering actions.
Document and commit version bumps with clear, conventional messages.

Example Use Cases

lisa github issues list --repo owner/repo --state open
lisa github issues create --repo owner/repo --title 'Bug: Login fails' --body 'Detailed report' --labels bug
lisa github projects add --repo owner/repo 1 123
lisa github sync --repo owner/repo --import
lisa github issues label --repo owner/repo 123 --add in-progress

Frequently Asked Questions

Add this skill to your agents

github

Purpose

Triggers

Configuration

How to use

Issues

List Issues

Create Issue

View Issue

Close/Reopen Issue

Assign Issue

Label Issue

Projects v2

List Projects

View Project

List Project Items

List Project Fields

Add Issue to Project

Update Project Field

Sync (Bidirectional Task Sync)

Import GitHub Issues as Lisa Tasks

Export Lisa Tasks to GitHub Issues

Bidirectional Sync

Status Mapping

I/O Contract (examples)

Create Issue

List Issues

View Issue

List Projects

Project Items

Project Fields

Sync Result

Error

Workflow Examples

Bug Triage Workflow

Sprint Planning Workflow

Task Sync Workflow

Git Workflows

Check PR Status

Retrigger CI Tests

Check CircleCI Pipeline Status

Poll CI Until Completion

Bump Version

Configuration

Workflow: Push with Version Bump

Workflow: PR Test Failure

Cross-model checklist

Notes

See Also

Source

Overview

How This Skill Works

When to Use It

Quick Start

Best Practices

Example Use Cases

Frequently Asked Questions

What can I manage with this skill?

How do I authenticate?

How do I target a specific repository?