Skip to content

Commit 8a0b442

Browse files
author
pragya247
committed
Initial release of Azure DevOps Integration extension v1.0.0
- Sync user stories from spec.md to Azure DevOps as User Story work items - Sync tasks from tasks.md to Azure DevOps as Task work items - Uses Azure CLI with OAuth authentication (no PAT tokens) - Interactive configuration for organization, project, and area path - Auto-links tasks to parent user stories - Saves mapping for tracking synced work items
0 parents  commit 8a0b442

9 files changed

Lines changed: 1862 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Azure DevOps Integration - Local Configuration
2+
# Do not commit this file!
3+
4+
# Azure DevOps configuration
5+
# This file is auto-generated when you run the sync command
6+
# Location: ~/.speckit/ado-config.json
7+
8+
# Editor-specific files
9+
.vscode/
10+
.idea/
11+
*.swp
12+
*.swo
13+
*~
14+
15+
# OS-specific files
16+
.DS_Store
17+
Thumbs.db
18+
desktop.ini
19+
20+
# Local configs (gitignored)
21+
ado-config.local.json
22+
*.local.json
23+
24+
# Python
25+
__pycache__/
26+
*.py[cod]
27+
*$py.class
28+
.Python
29+
venv/
30+
env/
31+
.env
32+
33+
# Node
34+
node_modules/
35+
npm-debug.log*
36+
37+
# Test files
38+
.pytest_cache/
39+
.coverage
40+
htmlcov/
41+
42+
# Build artifacts
43+
dist/
44+
build/
45+
*.egg-info/

‎CHANGELOG.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Changelog
2+
3+
All notable changes to the Azure DevOps Integration extension will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2026-03-03
9+
10+
### Added
11+
12+
- Initial release of Azure DevOps Integration extension
13+
- User Story sync from spec.md to Azure DevOps User Story work items
14+
- Task sync from tasks.md to Azure DevOps Task work items
15+
- OAuth authentication via Azure CLI (no PAT tokens required)
16+
- Interactive configuration with persistence to `~/.speckit/ado-config.json`
17+
- Work item mapping tracker in `.speckit/azure-devops-mapping.json`
18+
- Automatic priority mapping (P1-P4 to Azure DevOps priorities)
19+
- Task-to-User Story automatic linking via `[US#]` references
20+
- Hook integration with `/speckit.tasks` command
21+
- Support for both bash and PowerShell scripts
22+
- Interactive selection of which items to sync
23+
- Real-time progress feedback during sync
24+
- Summary table with work item IDs and URLs
25+
26+
### Documentation
27+
28+
- Comprehensive README with usage examples
29+
- Configuration reference
30+
- Troubleshooting guide
31+
- Field mapping documentation
32+
33+
### Scripts
34+
35+
- Bash script: `scripts/bash/create-ado-workitems.sh`
36+
- PowerShell script: `scripts/powershell/create-ado-workitems.ps1`
37+
38+
[1.0.0]: https://github.com/github/spec-kit-azure-devops/releases/tag/v1.0.0

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 GitHub Spec Kit Team
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Azure DevOps Integration Extension
2+
3+
Sync user stories and tasks from Spec Kit to Azure DevOps work items using OAuth authentication (no PAT tokens required).
4+
5+
## Features
6+
7+
- OAuth Authentication: Uses Azure CLI with OAuth flow - no Personal Access Tokens needed
8+
- User Story Sync: Create Azure DevOps User Story work items from spec.md
9+
- Task Sync: Create Azure DevOps Task work items from tasks.md, automatically linked to parent User Stories
10+
- Interactive Selection: Choose which user stories or tasks to sync
11+
- Configuration Persistence: Saves organization, project, and area path for reuse
12+
- Work Item Mapping: Tracks synced items to prevent duplicates
13+
- Priority Mapping: Automatically maps spec-kit priorities (P1-P4) to Azure DevOps priorities
14+
- Auto-Hook: Optional automatic sync after task generation
15+
16+
## Installation
17+
18+
```bash
19+
# Install from catalog (once published)
20+
specify extension add azure-devops
21+
22+
# Or install from local development directory
23+
specify extension add --dev /path/to/spec-kit-azure-devops
24+
```
25+
26+
## Prerequisites
27+
28+
- **Azure CLI**: Required for Azure DevOps API access
29+
- Windows: https://aka.ms/installazurecliwindows
30+
- macOS: `brew install azure-cli`
31+
- Linux: See https://docs.microsoft.com/cli/azure/install-azure-cli
32+
- **Azure DevOps Access**: Contributor or higher permissions on the target project
33+
- **Spec Kit**: Version 0.1.0 or higher
34+
35+
## Configuration
36+
37+
### Option 1: Interactive Configuration (Recommended)
38+
39+
The extension will prompt you for configuration the first time you use it:
40+
41+
1. **Organization**: Your Azure DevOps organization name (e.g., "MSFTDEVICES" from `https://dev.azure.com/MSFTDEVICES`)
42+
2. **Project**: Your Azure DevOps project name (e.g., "Devices")
43+
3. **Area Path**: Work item area path (e.g., "Devices\\SW\\ASPX\\CE\\Portals and Services")
44+
45+
Configuration is saved to `~/.speckit/ado-config.json` and reused for future syncs.
46+
47+
### Option 2: Manual Configuration
48+
49+
Create `~/.speckit/ado-config.json`:
50+
51+
```json
52+
{
53+
"Organization": "your-org-name",
54+
"Project": "your-project-name",
55+
"AreaPath": "your-area-path",
56+
"LastUpdated": "2026-03-03 10:30:00"
57+
}
58+
```
59+
60+
### Option 3: Environment Variables
61+
62+
Override configuration with environment variables:
63+
64+
```bash
65+
export AZURE_DEVOPS_ORG="your-org-name"
66+
export AZURE_DEVOPS_PROJECT="your-project-name"
67+
export AZURE_DEVOPS_AREA_PATH="your-area-path"
68+
```
69+
70+
## Usage
71+
72+
### Sync User Stories
73+
74+
```bash
75+
# In your AI agent (Claude, Copilot, etc.)
76+
> /speckit.azure-devops.sync
77+
78+
# Or use the shorter alias
79+
> /speckit.adosync
80+
```
81+
82+
The command will:
83+
84+
1. Ask for Azure DevOps configuration (if not already saved)
85+
2. Parse user stories from `spec.md`
86+
3. Display found stories and ask which ones to sync
87+
4. Create Azure DevOps User Story work items
88+
5. Display results with work item IDs and URLs
89+
90+
### Sync Tasks
91+
92+
```bash
93+
# Sync tasks from tasks.md
94+
> /speckit.adosync -FromTasks
95+
```
96+
97+
The command will:
98+
99+
1. Parse tasks from `tasks.md`
100+
2. Display found tasks grouped by User Story
101+
3. Ask which tasks to sync (can select by User Story or task number)
102+
4. Create Azure DevOps Task work items linked to parent User Stories
103+
5. Display results
104+
105+
### Automatic Hook After Task Generation
106+
107+
After running `/speckit.tasks`, you'll be prompted:
108+
109+
```text
110+
## Extension Hooks
111+
112+
**Optional Hook**: azure-devops
113+
Command: `/speckit.azure-devops.sync`
114+
Description: Automatically create Azure DevOps work items after task generation
115+
116+
Sync tasks to Azure DevOps? (yes/no)
117+
```
118+
119+
## Configuration Reference
120+
121+
### Saved Configuration (`~/.speckit/ado-config.json`)
122+
123+
| Setting | Type | Required | Description |
124+
| ------------- | ------ | -------- | --------------------------------------------------------- |
125+
| Organization | string | Yes | Azure DevOps organization name |
126+
| Project | string | Yes | Azure DevOps project name |
127+
| AreaPath | string | Yes | Work item area path (e.g., "Project\\Team\\Component") |
128+
| LastUpdated | string | No | Timestamp of last configuration update (auto-maintained) |
129+
130+
## Examples
131+
132+
### Example 1: First-Time Setup and Sync
133+
134+
```bash
135+
# Step 1: Create specification
136+
> /speckit.spec Create photo album management feature
137+
138+
# Step 2: Generate tasks
139+
> /speckit.tasks
140+
141+
# Step 3: Sync to Azure DevOps (will prompt for configuration)
142+
> /speckit.adosync
143+
```
144+
145+
## Troubleshooting
146+
147+
### Issue: Azure CLI not found
148+
149+
**Solution**: Install Azure CLI:
150+
151+
- Windows: https://aka.ms/installazurecliwindows
152+
- macOS: `brew install azure-cli`
153+
- Linux: Follow guide at https://docs.microsoft.com/cli/azure/install-azure-cli
154+
155+
### Issue: Azure DevOps extension not installed
156+
157+
**Solution**: The extension will auto-install it when needed:
158+
159+
```bash
160+
az extension add --name azure-devops
161+
```
162+
163+
### Issue: Authentication failed
164+
165+
**Solution**: Authenticate with Azure CLI:
166+
167+
```bash
168+
az login --use-device-code
169+
```
170+
171+
### Issue: Permission denied when creating work items
172+
173+
**Solution**: Ensure you have Contributor or higher permissions on the Azure DevOps project.
174+
175+
### Issue: Command not available in AI agent
176+
177+
**Solutions**:
178+
179+
1. Check extension is installed: `specify extension list`
180+
2. Restart your AI agent
181+
3. Reinstall extension: `specify extension remove azure-devops && specify extension add azure-devops`
182+
183+
## License
184+
185+
MIT License - see [LICENSE](LICENSE) file
186+
187+
## Support
188+
189+
- **Issues**: https://github.com/github/spec-kit-azure-devops/issues
190+
- **Spec Kit Docs**: https://github.com/github/spec-kit
191+
192+
## Changelog
193+
194+
See [CHANGELOG.md](CHANGELOG.md) for version history.
195+
196+
---
197+
198+
*Extension Version: 1.0.0*
199+
*Spec Kit: >=0.1.0*
200+
*Azure CLI: >=2.0.0*

0 commit comments

Comments
 (0)