Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/thgossler/azdo-wi-creator

A CLI tool for creating Azure DevOps work items from JSON specs.
https://github.com/thgossler/azdo-wi-creator

azure-devops create dotnet workitem

Last synced: 5 months ago
JSON representation

A CLI tool for creating Azure DevOps work items from JSON specs.

Awesome Lists containing this project

README 

          




  
Azure DevOps Work Item Creator


  
A command-line tool for creating and managing Azure DevOps work items in bulk from JSON specification files.








[![Contributors][contributors-shield]][contributors-url]

[![Forks][forks-shield]][forks-url]

[![Stargazers][stars-shield]][stars-url]

[![Issues][issues-shield]][issues-url]

[![MIT License][license-shield]][license-url]






## Features



- ✅ Create or update multiple work items from JSON specifications

- ✅ Support for multiple area paths (creates one work item per area path)

- ✅ Support for multiple projects in a single spec file

- ✅ Short field name support (use "Title" instead of "System.Title")

- ✅ Automatic markdown-to-HTML conversion for rich text fields

- ✅ Automatic tagging with `azdo-wi-creator` for tracking

- ✅ Smart spec file resolution (local paths, URLs, or simple names)

- ✅ Support for comments in JSON spec files (single-line `//` and multi-line `/* */`)

- ✅ Simulation mode (dry-run) to preview changes

- ✅ Work item protection (prevents accidental updates of non-tool-created items)

- ✅ List all work items created by the tool

- ✅ Cross-platform support (Windows, Linux, macOS - x64 and ARM64)

- ✅ Self-contained single-file executable



## Installation



Download the pre-built executable for your platform from the [Releases](../../releases) page.



Or build from source:



> Prerequisites:

> - Installed .NET 10 SDK ([Download .NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0))



```bash

git clone https://github.com/thgossler/azdo-wi-creator.git

cd azdo-wi-creator

dotnet publish -c Release

```



## Authentication



The tool supports multiple authentication methods in priority order:



1. **Force Interactive Sign-in**: Use the `--interactive-signin` flag to force browser-based authentication (ignores PAT and environment variable)

   ```bash

   azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --interactive-signin

   ```



2. **Command-line PAT option**: Use the `--pat` option to provide a Personal Access Token directly

   ```bash

   azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --pat "your-pat-token"

   ```



3. **Environment Variable**: Set the `AZURE_DEVOPS_PAT` environment variable

   ```bash

   export AZURE_DEVOPS_PAT="your-pat-token"

   azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature"

   ```



4. **Interactive Browser Sign-in** (default): If no PAT is provided, the tool will open a browser for you to sign in interactively (OAuth)

   ```bash

   # No PAT needed - browser will open for authentication

   azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature"

   ```



**Creating a PAT:**

1. Go to Azure DevOps → User Settings → Personal Access Tokens

2. Create a new token with **Work Items (Read, Write)** scope

3. Copy the token and use it with `--pat` option or set as environment variable



## Usage



### Create/Update Work Items



```bash

azdo-wi-creator create \

  --organization "https://dev.azure.com/myorg" \

  --project "MyProject" \

  --type "Bug" \

  --spec "feature-spec.json"

```



**Note**: The `--project` option is now optional if you specify the project in your spec file. See [Multi-Project Support](#multi-project-support) below.



**Short form:**

```bash

azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature"

```



**With PAT token:**

```bash

azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --pat "your-pat-token"

```



**Force interactive sign-in** (ignores PAT and environment variable):

```bash

azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --interactive-signin

```



**Default command** (can omit "create"):

```bash

azdo-wi-creator -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature"

```



### Simulation Mode (Dry-Run)



Preview what would be created without making any changes:



```bash

azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --simulate

```



### List Work Items Created by Tool



```bash

azdo-wi-creator list -o "https://dev.azure.com/myorg" -p "MyProject"

```



### Force Update



⚠️ **Use with caution!** Updates work items even if they weren't created by this tool:



```bash

azdo-wi-creator create -o "https://dev.azure.com/myorg" -p "MyProject" -t "Bug" -s "feature" --force

```



## Spec File Format



Create a JSON file with your work item specifications:



```json

{

  "workItems": [

    {

      "fields": {

        "Title": "My Bug Title",

        "Description": "
Bug description in HTML or markdown
",

        "AcceptanceCriteria": "- Criteria 1\n- Criteria 2",

        "Priority": 1,

        "Severity": "2 - High"

      },

      "areaPaths": [

        "MyProject\\Team1",

        "MyProject\\Team2"

      ],

      "tags": "bug-bash, high-priority"

    }

  ]

}

```



### Comments Support



You can use comments to document your spec files, explain decisions, or temporarily disable sections:



```json

{

    // This is a single-line comment

    /* 

     * This is a multi-line comment

     * explaining the work items below

     */

    "workItems": [

        {

            "project": "MyProject",

            "fields": {

                // Title field is required

                "Title": "Example Feature",

                "Description": "
Feature description
",

                "State": "New" // Can be: New, Active, Resolved, Closed

            },

            // Area paths define where the work item belongs

            "areaPaths": [

                "MyProject\\Team1",

                // You can comment out paths you don't need:

                // "MyProject\\Team2",

                "MyProject\\Team3"

            ],

            /* Tags help categorize work items */

            "tags": "example, feature"

        }

        // Add more work items here

    ]

}

```



**Note**: Your editor may show syntax warnings about comments in JSON files, but the tool handles them correctly. In Visual Studio Code use the JSONC syntax mode to avoid syntax error for "JSON with Comments" (jsonc).



### Field Name Resolution



You can use **short field names** for convenience! The tool automatically resolves them to fully qualified Azure DevOps reference names.



**Both formats work:**



```json

{

  "fields": {

    "Title": "My Feature",                    // Short name (easier to read)

    "System.Title": "My Feature"              // Fully qualified (explicit)

  }

}

```



**Supported short names** (40+ common fields):

- `Title` → `System.Title`

- `Description` → `System.Description`

- `State` → `System.State`

- `Priority` → `Microsoft.VSTS.Common.Priority`

- `AcceptanceCriteria` → `Microsoft.VSTS.Common.AcceptanceCriteria`

- `BusinessValue` → `Microsoft.VSTS.Common.BusinessValue`

- `Effort` → `Microsoft.VSTS.Scheduling.Effort`

- `Risk` → `Microsoft.VSTS.Common.Risk`

- `TargetDate` → `Microsoft.VSTS.Scheduling.TargetDate`

- And many more...



**Custom fields**: Always use fully qualified names (e.g., `Custom.MyCompanyField`)



### Automatic Markdown Detection



The tool **automatically detects markdown syntax and HTML tags** in string field values and creates corresponding HTML fields for rich text rendering in Azure DevOps!



**How it works:**



1. **System Fields** (e.g., `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`):

   - Stores original markdown/HTML in the field (e.g., `System.Description`)

   - Creates a separate `.Html` field with the HTML version (e.g., `System.Description.Html`)

   

2. **Custom Fields** (e.g., `Custom.ProblemStatement`, `Custom.FeatureHypothesis`):

   - Converts markdown to HTML and stores it directly in the field

   - No separate `.Html` field is created (custom fields don't support this in Azure DevOps)

   - Azure DevOps displays the HTML if the field is configured to support markdown/HTML



**Example with System Field:**



```json

{

  "fields": {

    "Description": "# Overview\n\n- Item 1\n- Item 2"

  }

}

```



Result:

- `System.Description` = "# Overview\n\n- Item 1\n- Item 2" (original markdown)

- `System.Description.Html` = "\
Overview\
\
    \
  • Item 1\
    • \
  • Item 2\
    • \
" (auto-generated)



**Example with Custom Field:**



```json

{

  "fields": {

    "Custom.ProblemStatement": "# Problem\n\n- Issue 1\n- Issue 2"

  }

}

```



Result:

- `Custom.ProblemStatement` = "\
Problem\
\
    \
  • Issue 1\
    • \
  • Issue 2\
    • \
" (converted to HTML)



**System fields that support .Html:**

- `System.Description`

- `System.History`

- `Microsoft.VSTS.Common.AcceptanceCriteria`

- `Microsoft.VSTS.TCM.ReproSteps`

- `Microsoft.VSTS.TCM.SystemInfo`



**Example with Markdown:**



```json

{

  "workItems": [

    {

      "fields": {

        "Title": "Implement User Authentication",

        "Description": "# Overview\n\nThis feature adds user authentication with the following:\n\n- **OAuth 2.0** support\n- *JWT tokens* for session management\n- Password reset functionality\n\n## Technical Details\n\n```javascript\nconst token = jwt.sign({ userId }, secret);\n```\n\nSee the [design doc](https://example.com) for more info.",

        "Custom.TechSpec": "## Architecture\n\n- Microservices\n- Event-driven\n- REST APIs"

      },

      "areaPaths": ["MyProject\\Team1"]

    }

  ]

}

```



**What happens:**

- `System.Description`: Markdown detected → creates both `System.Description` (original) and `System.Description.Html` (converted)

- `Custom.TechSpec`: Markdown detected → converts to HTML and stores in `Custom.TechSpec`

- Azure DevOps renders both beautifully



**Example with HTML:**



```json

{

  "workItems": [

    {

      "fields": {

        "Title": "Bug Fix",

        "Description": "
This is a critical bug that needs attention.

Steps to reproduce:
    

  • Step 1
    • 

  • Step 2
    • 

",

        "Custom.Notes": "Some text with 
 and emphasis"

      },

      "areaPaths": ["MyProject\\Team1"]

    }

  ]

}

```



**What happens:**

- `System.Description`: HTML detected → creates both `System.Description` (original) and `System.Description.Html` (same HTML)

- `Custom.Notes`: HTML detected → stores HTML directly in `Custom.Notes`

- Azure DevOps renders the HTML properly



**Supported Markdown:**

- Headers: `# H1`, `## H2`, `### H3`, etc.

- Bold: `**bold**` or `__bold__`

- Italic: `*italic*` or `_italic_`

- Links: `[text](url)`

- Code blocks: `` ```code``` ``

- Inline code: `` `code` ``

- Lists: `- item` or `* item` or `1. item`

- Blockquotes: `> quote`



**Supported HTML Tags:**

- Any valid HTML tags: `
`, ``, `
`, `
`, ``, ``, ``, `