GitHub Integration¶

TaskRepo integrates with GitHub for repository management, collaboration, and issue tracking.

Overview¶

GitHub integration enables: - Creating GitHub repositories for task collaboration - Linking tasks to GitHub issues and pull requests - Discovering existing TaskRepo repositories on GitHub - Syncing tasks across teams via GitHub remotes

Configuration¶

GitHub Organization¶

Set default GitHub organization in configuration:

tsk config

Set default_github_org to your GitHub username or organization name:

default_github_org: 'HenriquesLab'

Benefits: - Auto-used when creating repositories - Default for repository search - Simplifies collaboration setup

GitHub CLI¶

TaskRepo uses GitHub CLI (gh) for GitHub operations.

Installation:

# macOS
brew install gh

# Linux
sudo apt install gh  # Debian/Ubuntu
sudo dnf install gh  # Fedora

# Windows
winget install GitHub.cli

Authentication:

gh auth login

Follow prompts to authenticate with GitHub.

Verify:

gh auth status

Creating GitHub Repositories¶

Interactive Creation¶

When creating a task repository with default_github_org configured:

tsk create-repo

Prompts:

Repository name: project-tasks
Create GitHub repository? [y/N]: y

Result: - Creates local repository: ~/tasks/tasks-project-tasks/ - Creates GitHub repository: github.com/{org}/tasks-project-tasks - Adds remote and pushes initial commit

Manual GitHub Setup¶

For existing repositories without GitHub remotes:

cd ~/tasks/tasks-work

# Create GitHub repo with gh CLI
gh repo create {org}/tasks-work --private --source=. --remote=origin

# Push to GitHub
git push -u origin main

Public vs Private¶

Private repositories (recommended): - Task data remains confidential - Suitable for personal and team use - Requires repository access for collaboration

Public repositories: - Tasks visible to everyone - Useful for open-source project management - Consider privacy before making public

# Create public repository
gh repo create {org}/tasks-work --public --source=. --remote=origin

Discovering Repositories¶

Search GitHub¶

Find TaskRepo repositories in your organization:

tsk repos-search

With custom organization:

tsk repos-search --org HenriquesLab

Output:

Found 3 TaskRepo repositories:

1. tasks-project-alpha
   URL: https://github.com/HenriquesLab/tasks-project-alpha
   Clone: gh repo clone HenriquesLab/tasks-project-alpha ~/tasks/tasks-project-alpha

2. tasks-team-backend
   URL: https://github.com/HenriquesLab/tasks-team-backend
   Clone: gh repo clone HenriquesLab/tasks-team-backend ~/tasks/tasks-team-backend

3. tasks-research
   URL: https://github.com/HenriquesLab/tasks-research
   Clone: gh repo clone HenriquesLab/tasks-research ~/tasks/tasks-research

Clone Repository¶

Clone discovered repository:

cd ~/tasks
gh repo clone HenriquesLab/tasks-project-alpha

Verify:

tsk repos

Linking Tasks to GitHub¶

GitHub Issues¶

Link tasks to GitHub issues using the links field:

tsk add --repo work \
  --title "Fix authentication bug" \
  --links https://github.com/org/repo/issues/123

In task file:

links:
  - https://github.com/org/repo/issues/123

Display: Tasks with links show 🔗 indicator in lists

GitHub Pull Requests¶

Link to pull requests:

links:
  - https://github.com/org/repo/pull/456

Multiple GitHub Links¶

Tasks can reference multiple issues/PRs:

links:
  - https://github.com/org/repo/issues/123
  - https://github.com/org/repo/pull/456
  - https://github.com/org/repo/pull/789

Assignees and GitHub Handles¶

GitHub Handle Format¶

Assignees use GitHub handles with @ prefix:

assignees:
  - '@alice'
  - '@bob'

Benefits: - Consistent with GitHub mention syntax - Easy to identify collaborators - Supports filtering by assignee

Adding Assignees¶

# Interactive
tsk add
# Enter: @alice,@bob

# Non-interactive
tsk add --repo work --title "Task" --assignees @alice,@bob

Editing Assignees¶

tsk edit 1 --assignees @alice,@bob,@charlie

Default Assignee¶

For personal task management, set default assignee:

default_assignee: '@alice'

Behavior: New tasks without explicit assignees get default assignee automatically.

Collaboration Workflows¶

Shared Team Repository¶

Setup:

Create organization repository:

tsk create-repo --name team-backend
# Creates: github.com/{org}/tasks-team-backend

Team members clone:

cd ~/tasks
gh repo clone {org}/tasks-team-backend

Configure sync: Each team member syncs regularly:
```
tsk sync --repo team-backend --push
```

Workflow: - Team members create and edit tasks locally - Sync pulls others' changes - Conflicts resolved automatically or interactively - Everyone stays in sync

Personal + Shared Repositories¶

Setup: - Personal repository: Private, for individual tasks - Shared repository: Team collaboration

# Personal
tsk create-repo --name alice-personal
# Keep this private, don't push to GitHub

# Shared
cd ~/tasks
gh repo clone {org}/tasks-team-backend

Workflow: - Personal tasks in alice-personal - Team tasks in team-backend - Use tsk move to transfer tasks between repos if needed

Issue-Driven Task Management¶

Setup: Link TaskRepo tasks to GitHub issues for full traceability.

Workflow:

GitHub issue created:
```
Issue #123: Fix authentication bug
```

Create TaskRepo task linked to issue:

tsk add --repo work \
  --title "Fix authentication bug" \
  --links https://github.com/org/repo/issues/123

Work on task locally:

tsk in-progress 1
# Do work...
tsk done 1

Close GitHub issue:

gh issue close 123 --comment "Fixed in commit abc123"

Archive task:
```
tsk archive 1
```

GitHub Actions Integration¶

Automatic Sync¶

Set up GitHub Actions to validate task files on push:

.github/workflows/taskrepo-validate.yml:

name: Validate TaskRepo Tasks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install TaskRepo
        run: pipx install taskrepo

      - name: Validate task files
        run: |
          # Check YAML syntax
          for file in tasks/*.md; do
            echo "Validating $file"
            tsk info --file "$file" || exit 1
          done

PR Preview¶

Show task changes in pull requests:

.github/workflows/pr-task-summary.yml:

name: PR Task Summary

on:
  pull_request:
    types: [ opened, synchronize ]

jobs:
  summary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Install TaskRepo
        run: pipx install taskrepo

      - name: Generate task summary
        run: |
          echo "## Task Changes" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # List changed task files
          git diff --name-only origin/main...HEAD | grep "^tasks/" | while read file; do
            task_uuid=$(basename "$file" .md | sed 's/^task-//')
            echo "- Changed: \`$task_uuid\`" >> $GITHUB_STEP_SUMMARY
          done

Repository Naming Conventions¶

Standard Naming¶

TaskRepo repositories follow the pattern: tasks-{name}

Examples: - tasks-work - Work tasks - tasks-personal - Personal tasks - tasks-project-alpha - Project Alpha tasks - tasks-team-backend - Backend team tasks

GitHub Organization¶

Recommended structure:

github.com/{org}/
├── tasks-shared          # Organization-wide tasks
├── tasks-team-frontend   # Frontend team
├── tasks-team-backend    # Backend team
├── tasks-project-alpha   # Project-specific
└── tasks-research        # Research tasks

Benefits¶

Clear identification of TaskRepo repositories
Easy discovery with repos-search
Consistent organization
Avoid naming conflicts

Security Best Practices¶

Private by Default¶

Always use private repositories unless tasks are truly public:

gh repo create {org}/tasks-work --private --source=. --remote=origin

Access Control¶

Manage repository access via GitHub:

# Add collaborator
gh repo set-visibility {org}/tasks-work --public

# Manage access
gh repo edit {org}/tasks-work --add-collaborator @alice

Sensitive Information¶

Never commit: - Passwords or API keys - Personal identifiable information (PII) - Confidential business data

Use task links instead:

links:
  - https://internal-wiki.example.com/credentials/api-keys

Audit Commits¶

Review what's being committed:

cd ~/tasks/tasks-work
git status
git diff

Before syncing:

tsk sync  # Review changes before confirming push

Troubleshooting¶

GitHub CLI Not Found¶

Error: gh: command not found

Solution: Install GitHub CLI (see Configuration section above)

Not Authenticated¶

Error: gh: Not authenticated

Solution:

gh auth login

Repository Already Exists¶

Error: repository already exists

Solution: - Use different repository name - Or clone existing repository instead of creating new one

Push Rejected¶

Error: push rejected, remote has changes

Solution:

tsk sync  # Pull first, then push

Permission Denied¶

Error: permission denied

Solution: - Verify you have access to the repository - Check GitHub permissions - Ensure correct authentication

Advanced Integration¶

GitHub API via Scripts¶

Use GitHub API with TaskRepo:

import requests
import yaml

# Get task info
with open('tasks/task-{uuid}.md') as f:
    content = f.read()
    # Parse YAML frontmatter
    # Create GitHub issue
    # Update task with issue link

Webhook Integration¶

Set up webhooks to sync task status with GitHub issues:

Create webhook in GitHub repository settings
Point to server endpoint
Update TaskRepo tasks based on issue events

GitHub Projects¶

Sync TaskRepo tasks to GitHub Projects for visualization:

# Export tasks as JSON
tsk list --format json > tasks.json

# Import to GitHub Projects via API
# (custom script required)

Next Steps¶

Git Sync - Syncing with git remotes
Conflict Resolution - Handling merge conflicts
Repositories - Repository management