GitHub Projects for Obsidian

Manage GitHub Projects V2 with Kanban boards directly in Obsidian.

---

✨ Features

• 📋 Kanban Board View - Visualize your GitHub Projects V2 as interactive Kanban boards
• 🔄 Drag & Drop - Move items between columns with smooth drag-and-drop interactions
• 🎛️ Extensive Customization - Configure which fields appear on cards and in detail modals
• 🔐 Secure Authentication - Personal Access Token stored in localStorage (not synced with vault)
• ⚡ Real-time Sync - Auto-refresh project data from GitHub at configurable intervals
• 🎨 Theme Compatible - Seamlessly integrates with Obsidian themes (light & dark mode)
• 📱 Mobile Support - Works on desktop and mobile (iOS/Android)
• 🔍 Powerful Filtering - Filter by assignee, state, type, or search across titles and descriptions
• 💬 Card Details - Click any card to view full details, comments, and metadata

📦 Installation

From Obsidian Community Plugins (Recommended)

1. Open Settings in Obsidian
2. Navigate to Community Plugins and disable Safe Mode
3. Click Browse and search for "GitHub Projects"
4. Click Install, then Enable

Manual Installation

1. Download the latest release from GitHub releases
2. Extract main.js, manifest.json, and styles.css to {VaultFolder}/.obsidian/plugins/github-projects/
3. Reload Obsidian
4. Enable the plugin in Settings → Community Plugins

🚀 Quick Start

1. Create a GitHub Personal Access Token

For Fine-Grained Tokens (Recommended):

1. Go to GitHub Settings → Personal access tokens → Fine-grained tokens
2. Click "Generate new token"
3. Configure permissions:
   • Projects: Read and Write (required)
   • Metadata: Read (required for organization access)
   • Contents: Read (required for private repositories)
4. Copy the token (starts with github_pat_)

For Classic Tokens:

1. Go to GitHub Settings → Personal access tokens
2. Click "Generate new token (classic)"
3. Select the following scopes:
   • project - Required for project access
   • read:org - Required for organization dropdown/selector
   • repo - Required for private repositories
4. Copy the token (starts with ghp_)

2. Configure the Plugin

1. Open Obsidian Settings → GitHub Projects
2. Paste your token
3. (Optional) Set a default project:
   • Choose Personal Account or Organization
   • For organizations, enter the org name (e.g., my-org)
   • Enter the project number (from URL: github.com/orgs/my-org/projects/5 → 5)
   • Leave empty to use the project selector dropdown

3. Open Your Board

• Click the dashboard icon (📋) in the ribbon, or
• Use command palette: "GitHub Projects: Open Project Board"

4. Customize Your View (Optional)

You can now customize what information appears on cards and in detail modals:

1. Go to Obsidian Settings → GitHub Projects
2. Scroll to Card Display Settings to configure:
   • Card title length
   • Show/hide repository, labels, description, milestone, etc.
   • Maximum number of labels and assignees to display
   • Description truncation length
   • Engagement metrics (comments, reactions)
3. Scroll to Detail Modal Settings to configure:
   • Show/hide status badges, repository, labels, assignees
   • Show/hide author, reviewers, milestone, PR changes
   • Show/hide engagement metrics, timeline, comments

All settings are saved and applied immediately to give you complete control over your workflow.

📖 Documentation

• User Guide - Installation, setup, and usage instructions
• Developer Guide - Contributing and development setup
• Architecture - Technical design and architecture
• API Reference - Plugin API documentation

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• Obsidian installed

Quick Setup

# Clone the repository
git clone https://github.com/alexnodeland/obsidian-github-projects.git
cd obsidian-github-projects

# Install dependencies
npm install

# Build the plugin
npm run build

# Run tests
npm test

# Start development mode (auto-rebuild and copy to vault)
make dev VAULT=/path/to/your/vault

Available Commands

# Development
make dev VAULT=/path/to/vault   # Start development mode
make build                       # Production build
make test                        # Run tests
make coverage                    # Run tests with coverage

# Quality Checks
make lint                        # Run linter
make typecheck                   # Type checking
make check                       # Run all checks (lint + typecheck + test)

# Utilities
make clean                       # Clean build artifacts
make help                        # Show all available commands

See the Developer Guide for detailed instructions.

🏗️ Architecture

The plugin is built with:

• TypeScript - Type-safe code
• Preact - Lightweight React alternative (3KB)
• SortableJS - Smooth drag-and-drop
• GitHub GraphQL API - Projects V2 integration
• Obsidian Plugin API - Native Obsidian integration

Key architectural decisions:

• Event-driven state management for reactive UI
• Optimistic updates for responsive user experience
• Secure token storage in localStorage (not vault files)
• Virtual DOM rendering for performance

Learn more in the Architecture documentation.

🧪 Testing

We maintain high test coverage and code quality:

npm test                  # Run tests
npm run test:watch        # Watch mode
npm run test:coverage     # Generate coverage report

Coverage reports are available on Codecov.

🤝 Contributing

Contributions are welcome! We appreciate:

• 🐛 Bug reports
• ✨ Feature requests
• 📖 Documentation improvements
• 💻 Code contributions
• 🎨 UI/UX enhancements

Please read our Contributing Guide and Developer Guide before submitting PRs.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Run checks: make check
5. Commit: git commit -m "feat: add amazing feature"
6. Push and create a PR

📝 Changelog

See CHANGELOG.md for release history and changes.

🔒 Security

• Tokens are stored in localStorage (not in vault files)
• Tokens are not synced via Obsidian Sync
• Use fine-grained tokens with minimal permissions
• Set token expiration for additional security

See the User Guide for more details.

❓ FAQ

Q: Can I use multiple projects? A: Yes! Use the project selector dropdown to switch between projects, or set a default in settings.

Q: Does this work with personal projects? A: Yes! Select any personal project in the project selector dropdown, or set your default to "Personal".

Q: Can I create new issues from Obsidian? A: Not yet. This feature is planned for a future release.

Q: What about rate limits? A: The plugin uses GitHub's GraphQL API (5,000 points/hour). Normal usage stays well within limits.

See the full FAQ in the User Guide.

🙏 Acknowledgments

• Obsidian - For creating an amazing platform
• obsidian-kanban - Inspiration for board UI
• Preact - Lightweight UI framework
• SortableJS - Drag-and-drop functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Documentation: docs/
• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Questions: GitHub Discussions Q&A

---

⭐ Star this repo if you find it helpful!

Made with ❤️ for the Obsidian community

Report Bug · Request Feature · Documentation