GitHub setup

GitHub Integration

imdone-cli fully supports GitHub Issues as an alternative to Jira. This allows teams using GitHub to benefit from the same context-driven development workflow.

Supported Features

• imdone init with GitHub provider selection
• imdone pull to fetch GitHub issues, comments, and attachments into local markdown files
• imdone push to sync local changes back to GitHub (content, comments, and attachments)
• imdone add to create new GitHub issues with template support
• imdone ls to list GitHub issues with custom queries
• imdone template to apply templates to GitHub issues
• Comment synchronization (via imdone pull and imdone push)
• Attachment synchronization — add, modify, delete, and rename attachments locally; changes sync bidirectionally
• Auto-detection of GitHub owner/repo from git remote origin
• Status mapping (open/closed → TODO/DOING/DONE)
• Optional label-based status mapping for GitHub workflow labels like code-review
• Label support (template tags automatically converted to labels)

Getting Started with GitHub

1. Initialize with GitHub:

   imdone init
   # Select "github" when prompted for provider
   

2. GitHub automatically detects your repository:

   • Owner and repo are extracted from your git remote origin URL
   • Supports HTTPS and Git-style SSH remote URLs, including git@github.com:owner/repo.git, ssh://git@github.com/owner/repo.git, and git+ssh://git@github.com/owner/repo.git

3. If you enter the repository URL manually during imdone init:

   • The prompt shows accepted examples for HTTPS and SSH forms up front
   • Invalid input repeats those accepted examples instead of implying HTTP-only setup

4. Provide your GitHub Personal Access Token:

   • Create a classic token at: https://github.com/settings/tokens/new?scopes=repo
   • Or create a fine-grained token with repository Contents: Read and write, Issues: Read and write, and Pull requests: Read and write
   • Under Repository access, choose Only select repositories, then confirm your target repo appears under Selected repositories before you generate the token
   • If GitHub still shows 0 selected repositories, re-select the repo there or use a classic token instead
   • Token is stored securely in .env file

5. Inspect your synced GitHub issues:

   ls backlog/current-sprint
   

GitHub-Specific Features

Query Syntax: GitHub uses a simplified query syntax (not JQL):

• is:open - Open issues
• is:closed - Closed issues
• label:bug - Issues with “bug” label
• milestone:v1.0 - Issues in “v1.0” milestone
• assignee:username - Issues assigned to specific user

Directory Structure: Same as Jira — each issue gets its own folder, including an attachments/ subdirectory:

backlog/
├── current-sprint/
│   ├── 1-Fix_login_bug/
│   │   ├── attachments/
│   │   │   ├── screenshot.png
│   │   │   └── .metadata.yml
│   │   ├── comments-1.md
│   │   └── issue-1.md
│   └── 2-Add_dashboard/
│       ├── attachments/
│       └── issue-2.md

Pull Request (PR) Support

When syncing issues from GitHub, imdone automatically detects pull requests and provides special handling:

• Directory Naming: PRs get a PR- prefix in their directory names for easy visual identification:

  • Regular issue: 123-my-issue-title/
  • PR issue: PR-456-fix-bug/

• PR Metadata: Local-only metadata fields are added to PR issues (filtered from push to GitHub):

  • isPullRequest - Boolean, true if the issue is a PR
  • prSourceBranch - Source branch name (e.g., feature/my-feature)
  • prTargetBranch - Target branch name (e.g., main)
  • prMergedAt - Merge timestamp (ISO 8601) if the PR was merged

• Filtering PRs: Use the ls command with metadata filters:

  # List all PRs
  imdone ls meta.isPullRequest=true
  
  # List merged PRs only
  imdone ls meta.prMergedAt=*
  
  # Filter by source branch
  imdone ls meta.prSourceBranch=feature/my-feature
  
  # Filter by target branch
  imdone ls meta.prTargetBranch=main
  

Reactions Metadata

GitHub issue reactions are synced as individual metadata fields (local-only, filtered from push):

Filter by reactions:

# Issues with 5+ thumbs up
imdone ls meta.reactionThumbsUp=5..

# Issues with any heart reactions
imdone ls meta.reactionHeart=1..

# Issues with any reactions at all
imdone ls meta.reactionTotal=1..

Jira-Specific Metadata

Jira issues include additional metadata fields synced from Jira custom fields:

For engineers working in Jira projects with custom workflows, statusName keeps the exact workflow state visible in the local issue file. The existing status metadata remains the Jira status category, and statusName is not written into provider-side issue body metadata.

Blocked Field:

• Automatically detected from Jira “Flagged” or “Blocked” custom fields
• Value can be any string set in Jira (e.g., “Impediment”, “Blocked”, “Yes”)
• Used by shared-context reports to identify blockers and provide unblock advice

Filter by Jira-specific fields:

# Show all blocked/flagged issues
imdone ls -q 'meta.blocked=*'

# Filter by epic
imdone ls -q 'meta.epic=PROJ-100'

GitHub vs Jira Feature Comparison

GitHub Attachments

GitHub doesn’t have a native attachments API, so imdone-cli uses a dedicated imdone-attachments branch to give you the same local attachment workflow you get with Jira.

How it works:

• Storage: Files are stored on a dedicated branch named imdone-attachments, under a top-level _imdone-attachments/ folder with stable per-issue paths such as _imdone-attachments/{issueNumber}/{filename}.
• Branch-backed current set: imdone pull reads the current attachment list from the branch tree/Contents API. GitHub issue comments are not used as an attachment ledger and new machine-readable attachment comments are not posted.
• Stable content updates: When an attachment’s content changes but its filename does not, imdone updates the existing branch-backed file path and uses GitHub’s content SHA for change detection and concurrency protection.
• Rename/delete cleanup: When a GitHub attachment is renamed or deleted locally, imdone push removes the old stable path from the imdone-attachments branch so the old filename does not reappear on the next pull.
• History: Attachment history comes from GitHub branch commits for _imdone-attachments/{issueNumber}/{filename}.
• Link rewriting: Local links like [plan.md](./attachments/plan.md) are automatically converted to the current GitHub attachment URL on push, and back to local paths (original filename) on pull — exactly like Jira.
• Explicit repo-link refresh: imdone push --rewrite-repo-links is the GitHub escape hatch when you want touched issue content and in-scope text attachments republished so repo-relative markdown links resolve to the current source repo web URLs.

Required token permissions:

Your GitHub Personal Access Token must include either the classic repo scope or, for a fine-grained token, repository Contents: Read and write, Issues: Read and write, and Pull requests: Read and write. For fine-grained tokens, Repository access must also include the target repo, and you should confirm the repo appears under GitHub’s Selected repositories list before generating the token. If GitHub still shows 0 selected repositories, re-select the repo there or use a classic token. imdone needs these permissions to read and update issues/comments, access PR-backed cards, and create or update attachment files in the imdone-attachments branch.

Example workflow:

# Pull issues and their existing attachments
imdone pull

# Add a planning doc
cp ~/Desktop/plan.md backlog/current-sprint/1-Fix_login_bug/attachments/

# Push — uploads the file to the attachments branch
imdone push
# ✓ Uploaded: 1/plan.md → https://github.com/owner/repo/blob/imdone-attachments/_imdone-attachments/1/plan.md
# (locally the link stays as ./attachments/plan.md)

# Modify an attachment and push again
# (updates the current branch-backed file path; sibling links stay stable)
imdone push
# ✓ Updated: 1/plan.md

# If repo-relative markdown links need to be republished against the current source repo mapping
imdone push --rewrite-repo-links
# ✓ Rewrote touched repo-relative links to current source repo web URLs

Example Workflow

# 1. Initialize with GitHub
imdone init

# 2. Edit issues in your editor
code backlog/current-sprint/

# 3. Sync changes
imdone push