Skip to content

Commit a0cc817

Browse files
tikazyqtikazyq
committed
feat: Add enterprise integrations for Jira, Azure DevOps, and GitHub
- Introduced DOGFOODING.md to document the use of devlog for tracking its own development. - Created INTEGRATIONS.md as a setup guide for configuring devlog with enterprise project management tools. - Added a configuration template (devlog-integrations.config.template.json) for integration settings. - Enhanced DevlogManager to support syncing with Jira, Azure DevOps, and GitHub, including methods for creating and updating issues/work items. - Implemented MCP server integration tools for syncing devlog entries with external platforms. - Developed scripts for creating integration devlogs and demonstrating integration functionalities. - Updated README.md to include information about enterprise integrations and quick setup instructions.
1 parent 58c2a74 commit a0cc817

File tree

9 files changed

+1282
-5
lines changed

9 files changed

+1282
-5
lines changed

‎DOGFOODING.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Dogfooding Example: Devlog Tracking Its Own Development
2+
3+
This document shows how the `devlog` project is using itself to track the development of enterprise integrations feature - a perfect example of "eating your own dog food."
4+
5+
## The Meta-Development Entry
6+
7+
We created a devlog entry to track the enterprise integrations feature development:
8+
9+
```json
10+
{
11+
"id": "enterprise-platform-integratio-1750603245642",
12+
"title": "Enterprise Platform Integrations (Jira, ADO, GitHub)",
13+
"type": "feature",
14+
"status": "in-progress",
15+
"priority": "high",
16+
"description": "Implement bi-directional sync capabilities with enterprise project management platforms to bridge devlog with existing workflows",
17+
"context": {
18+
"businessContext": "Development teams need to integrate devlog with their existing project management tools...",
19+
"technicalContext": "Implement REST API integrations with authentication, field mapping, and error handling...",
20+
"acceptanceCriteria": [
21+
"Can create Jira issues from devlog entries",
22+
"Can update existing Jira issues when devlog changes",
23+
"Can create Azure DevOps work items from devlog entries",
24+
"Can update existing ADO work items when devlog changes",
25+
"Can create GitHub issues from devlog entries",
26+
"Can update existing GitHub issues when devlog changes",
27+
"Proper error handling and user feedback",
28+
"Secure credential management",
29+
"Field mapping between devlog and external systems",
30+
"MCP tools for sync operations"
31+
]
32+
},
33+
"aiContext": {
34+
"keyInsights": [
35+
"Each platform has different authentication mechanisms (API tokens, PATs, OAuth)",
36+
"Field mapping is critical - devlog types need to map to platform-specific issue types",
37+
"External references should be stored in devlog entries for tracking",
38+
"Need to handle both creation and updates to avoid duplicates",
39+
"Different platforms have different priority systems",
40+
"REST API integration requires careful error handling for network issues",
41+
"Each platform has unique field structures that need mapping functions",
42+
"Configuration should support both file-based and environment variable approaches",
43+
"MCP adapter pattern works well for exposing integration features to AI agents"
44+
],
45+
"suggestedNextSteps": [
46+
"Test integrations with real platform instances",
47+
"Add webhook support for real-time bi-directional sync",
48+
"Implement batch sync operations for multiple devlog entries",
49+
"Add integration status monitoring and health checks"
50+
]
51+
}
52+
}
53+
```
54+
55+
## Benefits of Self-Tracking
56+
57+
By using devlog to track its own development, we've demonstrated several key benefits:
58+
59+
### 1. Real-World Testing
60+
- The devlog system gets immediate real-world usage
61+
- We discover UX issues and missing features organically
62+
- Performance characteristics become apparent with actual data
63+
64+
### 2. Living Documentation
65+
- The development process becomes self-documenting
66+
- Decision history is preserved with rationale
67+
- Progress tracking provides metrics on development velocity
68+
69+
### 3. AI Context Preservation
70+
- Key insights about the integration development are preserved
71+
- Next steps are clearly documented for future sessions
72+
- Technical context ensures continuity across development cycles
73+
74+
### 4. Feedback Loop
75+
- Issues with the devlog system surface immediately
76+
- Feature gaps become obvious during real usage
77+
- Improvements benefit the current development process
78+
79+
## Example Usage Scripts
80+
81+
We created several scripts to interact with our own devlog data:
82+
83+
### Create Integration Devlog
84+
```bash
85+
node scripts/create-integration-devlog.mjs
86+
```
87+
88+
This script creates the integration feature devlog entry with:
89+
- Comprehensive business and technical context
90+
- Detailed acceptance criteria
91+
- Initial insights and patterns
92+
- AI-optimized context for future sessions
93+
94+
### Demo Integrations
95+
```bash
96+
node scripts/demo-integrations.mjs
97+
```
98+
99+
This script demonstrates:
100+
- Searching for devlog entries
101+
- Displaying AI context and insights
102+
- Showing acceptance criteria
103+
- Available integration methods
104+
- Current development statistics
105+
106+
## Impact on Development
107+
108+
Using devlog to track its own development has:
109+
110+
1. **Accelerated Development**: AI maintains better context across sessions
111+
2. **Improved Quality**: Real-world testing catches issues early
112+
3. **Generated Insights**: Better understanding of how devlog should evolve
113+
4. **Created Documentation**: Natural byproduct of the development process
114+
5. **Validated Value Proposition**: Concrete evidence that devlog works
115+
116+
## Current Statistics
117+
118+
As of the latest update:
119+
- **Total Entries**: 2
120+
- **In Progress**: 1
121+
- **Features**: 2
122+
- **High Priority**: 2
123+
124+
The integration feature represents 50% of our current active development, demonstrating the significant investment in enterprise connectivity.
125+
126+
## Next Steps
127+
128+
The self-tracking reveals our next priorities:
129+
1. Test integrations with real platform instances
130+
2. Add webhook support for real-time bi-directional sync
131+
3. Implement batch sync operations for multiple devlog entries
132+
4. Add integration status monitoring and health checks
133+
134+
This meta-approach creates a virtuous cycle where improvements to devlog immediately benefit the development of devlog itself, accelerating overall progress and ensuring the tool meets real-world needs.

‎INTEGRATIONS.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Enterprise Integrations Setup Guide
2+
3+
This guide helps you configure devlog to sync with enterprise project management tools like Jira, Azure DevOps, and GitHub.
4+
5+
## Configuration File Setup
6+
7+
Create a configuration file named `devlog-integrations.config.json` in one of these locations:
8+
- Your project root directory
9+
- `~/.devlog-integrations.config.json` (global config)
10+
- `.devlog/integrations.config.json` (workspace-specific)
11+
12+
Copy the template from `devlog-integrations.config.template.json` and fill in your credentials.
13+
14+
## Platform-Specific Setup
15+
16+
### Jira Integration
17+
18+
1. **Get your Jira API Token:**
19+
- Go to https://id.atlassian.com/manage-profile/security/api-tokens
20+
- Click "Create API token"
21+
- Copy the generated token
22+
23+
2. **Configuration:**
24+
```json
25+
{
26+
"integrations": {
27+
"jira": {
28+
"baseUrl": "https://your-company.atlassian.net",
29+
"projectKey": "PROJ",
30+
"apiToken": "your-jira-api-token",
31+
"userEmail": "[email protected]"
32+
}
33+
}
34+
}
35+
```
36+
37+
3. **Required Permissions:**
38+
- Browse projects
39+
- Create issues
40+
- Edit issues
41+
- View development tools (optional, for linking commits)
42+
43+
### Azure DevOps Integration
44+
45+
1. **Get your Personal Access Token (PAT):**
46+
- Go to https://dev.azure.com/{organization}/_usersSettings/tokens
47+
- Click "New Token"
48+
- Select scopes: Work Items (Read & write)
49+
- Copy the generated token
50+
51+
2. **Configuration:**
52+
```json
53+
{
54+
"integrations": {
55+
"ado": {
56+
"organization": "your-organization",
57+
"project": "your-project",
58+
"personalAccessToken": "your-ado-pat"
59+
}
60+
}
61+
}
62+
```
63+
64+
3. **Required Permissions:**
65+
- Work Items: Read & Write
66+
- Project and Team: Read (for project access)
67+
68+
### GitHub Integration
69+
70+
1. **Get your GitHub Token:**
71+
- Go to https://github.com/settings/tokens
72+
- Click "Generate new token (classic)"
73+
- Select scopes: `repo` (for private repos) or `public_repo` (for public repos)
74+
- Copy the generated token
75+
76+
2. **Configuration:**
77+
```json
78+
{
79+
"integrations": {
80+
"github": {
81+
"owner": "your-github-username",
82+
"repo": "your-repository",
83+
"token": "your-github-token"
84+
}
85+
}
86+
}
87+
```
88+
89+
3. **Required Permissions:**
90+
- Issues: Read & Write
91+
- Repository contents: Read (for context)
92+
93+
## Usage Examples
94+
95+
### Creating and Syncing a Devlog
96+
97+
```typescript
98+
// Create a devlog entry
99+
const entry = await devlog.createDevlog({
100+
title: "Implement user authentication",
101+
type: "feature",
102+
description: "Add JWT-based authentication system",
103+
priority: "high",
104+
businessContext: "Users need secure login to access protected features",
105+
technicalContext: "Using JWT tokens with refresh mechanism"
106+
});
107+
108+
// Sync with all configured platforms
109+
await devlog.syncAllIntegrations(entry.id);
110+
111+
// Or sync with specific platforms
112+
await devlog.syncWithJira(entry.id);
113+
await devlog.syncWithGitHub(entry.id);
114+
await devlog.syncWithADO(entry.id);
115+
```
116+
117+
### MCP Tools
118+
119+
The following MCP tools are available for integrations:
120+
121+
- `sync_with_jira` - Sync devlog entry with Jira
122+
- `sync_with_ado` - Sync devlog entry with Azure DevOps
123+
- `sync_with_github` - Sync devlog entry with GitHub
124+
- `sync_all_integrations` - Sync with all configured platforms
125+
126+
## Field Mappings
127+
128+
### Devlog Type to External Systems
129+
130+
| Devlog Type | Jira Issue Type | ADO Work Item Type | GitHub Labels |
131+
|-------------|----------------|-------------------|---------------|
132+
| feature | Story | User Story | feature |
133+
| bugfix | Bug | Bug | bugfix |
134+
| task | Task | Task | task |
135+
| refactor | Task | Task | refactor |
136+
| docs | Task | Task | docs |
137+
138+
### Priority Mappings
139+
140+
| Devlog Priority | Jira Priority | ADO Priority | GitHub Labels |
141+
|-----------------|---------------|--------------|---------------|
142+
| low | Low | 4 | - |
143+
| medium | Medium | 3 | - |
144+
| high | High | 2 | priority-high |
145+
| critical | Highest | 1 | priority-high |
146+
147+
## Security Considerations
148+
149+
1. **Never commit credentials to version control**
150+
2. **Use environment variables for sensitive data**
151+
3. **Regularly rotate API tokens and PATs**
152+
4. **Use the principle of least privilege for permissions**
153+
5. **Consider using organizational secrets management**
154+
155+
## Troubleshooting
156+
157+
### Common Issues
158+
159+
1. **Authentication Errors:**
160+
- Verify API tokens/PATs are correct and not expired
161+
- Check that email matches Jira account (for Jira)
162+
- Ensure permissions are correctly set
163+
164+
2. **Network Issues:**
165+
- Verify URLs are accessible from your network
166+
- Check for corporate firewall restrictions
167+
- Confirm SSL/TLS certificates are valid
168+
169+
3. **Permission Errors:**
170+
- Verify account has required permissions on the target system
171+
- Check project access permissions
172+
- Ensure work item types exist (for ADO)
173+
174+
### Debug Mode
175+
176+
Set environment variable `DEBUG=devlog:*` to enable debug logging:
177+
178+
```bash
179+
DEBUG=devlog:* pnpm start
180+
```
181+
182+
## Advanced Configuration
183+
184+
### Custom Field Mappings
185+
186+
You can extend the field mappings by modifying the mapping functions in `devlog-manager.ts`:
187+
188+
- `mapDevlogTypeToJiraIssueType()`
189+
- `mapDevlogTypeToADOWorkItemType()`
190+
- `mapDevlogPriorityToJiraPriority()`
191+
- `mapDevlogPriorityToADOPriority()`
192+
193+
### Webhook Integration (Future)
194+
195+
Future versions will support webhooks for real-time synchronization:
196+
197+
- Jira → Devlog updates
198+
- ADO → Devlog updates
199+
- GitHub → Devlog updates
200+
201+
## Environment Variables
202+
203+
Alternative to config file, you can use environment variables:
204+
205+
```bash
206+
# Jira
207+
DEVLOG_JIRA_BASE_URL=https://your-company.atlassian.net
208+
DEVLOG_JIRA_PROJECT_KEY=PROJ
209+
DEVLOG_JIRA_API_TOKEN=your-token
210+
[email protected]
211+
212+
# Azure DevOps
213+
DEVLOG_ADO_ORGANIZATION=your-org
214+
DEVLOG_ADO_PROJECT=your-project
215+
DEVLOG_ADO_PAT=your-pat
216+
217+
# GitHub
218+
DEVLOG_GITHUB_OWNER=your-username
219+
DEVLOG_GITHUB_REPO=your-repo
220+
DEVLOG_GITHUB_TOKEN=your-token
221+
```

0 commit comments

Comments
 (0)