Known Issues Support YAML Task Parameters Linking Attachments Duplicates Outputs Advanced Bulk Mode

Create Work Item

The Create Work Item task allows you to create a work item from a build or release.

Change Notes

You can find the changes notes for this task here.

Known Issues

Support

If you need help with the extension, run into issues, or have feedback or ideas for new features, please contact us at psgerextsupport@microsoft.com or create an issue here.

Adding the Task to a YAML Definition

To add the Create Work Item task to a YAML build or release definition, use the task name and major version like this - task: CreateWorkItem@1 and set a display name using the displayName property. Then add all task inputs as described under Task Parameters.

YAML snippet:

# Create or update a work item
- task: CreateWorkItem@2
  displayName: 'Create work item'
  inputs:
    #teamProject: # Optional
    workItemType: 
    title: 
    #assignedTo: # Optional
    #areaPath: # Optional
    #iterationPath: # Optional
    #fieldMappings: # Optional; Required if your process defines additional required work item fields
    #associate: false # Optional
    #associationType: build # Optional; Valid values: build, integratedInBuild, foundInBuild
    # ===== Linking Inputs =====
    #linkWorkItems: false # Optional
    #linkType: # Required if linkWorkItems = true
    #linkTarget: id # Optional; Valid values: id, wiql
    #targetId: # Required if linkWorkItems = true and linkTarget = id
    #targetWiql: # Required if linkWorkItems = true and linkTarget = wiql
    #limitWorkItemLinksToSameProject: false # Optional
    #linkPR: false # Optional
    #linkCode: false # Optional
    #codeReferences: # Required if linkCode = true (alias: commitsAndChangesets)
    # ===== Attachments Inputs =====
    #addAttachments: false # Optional
    #attachmentsFolder: # Optional
    #attachments: # Required if addAttachments = true
    # ===== Duplicate Inputs =====
    #preventDuplicates: false # Optional
    #keyFields: # Required if preventDuplicates = true
    #updateDuplicates: false # Optional
    #updateRules: # Optional
    # ===== Outputs Inputs =====
    #createOutputs: false # Optional
    #outputVariables: # Required if createOutputs = true
    # ===== Advanced Inputs =====
    #authType: internal # Optional; Valid values: internal, oidc, pat
    #targetOrg: # Optional; Only used if authType = pat or authType = oidc
    #authToken: # Required if authType = pat
    #serviceConnection: # Required if authType = oidc
    #allowRedirectDowngrade: false # Optional
    # ===== Bulk Mode =====
    #bulkMode: false # Optional
    #bulkConfigData: # Required if bulkMode = true

Task Parameters

The task supports the default parameters listed below. All parameters support variables including nested variables.

Security Note: For security reasons we mask all secrets automatically. This ensures that you cannot exploit the Create Work Item task to gain access to secret values stored in Azure DevOps. Please be aware, though, that it usually isn’t a good idea to try putting secrets in work item fields in the first place.

Default Task Parameters

The best way to specify an identity value is by using the VSID (i.e., the internal user ID of the identity). Most of the time, though, you don’t know this ID without using an Azure DevOps REST API call. However, if you want to assign the work item to the person who requested the build or release, you can use the $(Build.RequestedForId) or $(Release.Deployment.RequestedForId) variables. These variables contain the VSID of the user who requested the build or release.

The second-best option for specifying an identity is to use the UPN (User Principal Name; e.g., user@domain.com) or the SamAccountName (for on-premises Azure DevOps Servers; e.g., domain\user) of the identity. When using the UPN, please ensure that this is the actual login email address and not a preferred notification email address or alternate email address from Microsoft Entra.

Finally, you can also use the display name of the identity, but this is not recommended since it might not be unique and may lead to unexpected results. If you use the display name, please ensure that it is unique in your Azure DevOps organization or Azure DevOps Server instance.

YAML: assignedTo - (Optional) Default is empty.

Linking

Use the parameters in the Linking group to control links from the newly created work item to already existing work items:

Work Item Linking Parameters

Attachments

Use the parameters in the Attachments group to attach files to the new or updated work item.

Security Note: Please be careful not to attach any files that may contain sensitive data (e.g., memory dumps). If you really need those files, please ensure that you restrict access to the work item using area permissions in Azure DevOps.

Attachments Parameters

Duplicates

Use the parameters in the Duplicates group to control handling of duplicates that might be created by the task:

Duplicate Handling Parameters

Outputs

Use the parameter in the Output Variables group to control the creation of output variables that can be used by subsequent tasks:

Outputs Parameters

Standard Output Variables
In addition to the custom defined output variables the task automatically creates the following output variables:

Advanced

Use the parameter in the Advanced group to control special task features:

Note: Organizations might still be using the old URI format https://yourOrg.visualstudio.com instead of the new format https://dev.azure.com/yourOrg. While cross-organization work item creation should work, regardless of the URI format used by source and target organization, we cannot guarantee that it does and will always work. If you encounter problems when trying to create work items in organizations with a different URI format, please provide the full target organization URI instead of just the name.

YAML: targetOrg - (Optional) Default is empty.

Bulk Mode

Bulk mode allows you to create multiple work items in one go. Since the primary use case of this task is to create or update a single work item, bulk mode requires JSON configuration and is not supported through the regular task parameters (see below).

Important: There is no feasible way to implement something like a transaction for this task. Thus, bulk mode executes each work item creation/update sequentially. If one of these actions fails, the task will fail even though work items may have been created/updated. Be mindful about possible side-effects this might create!

Icons made by Pavel Kozlov from https://www.flaticon.com is licensed by CC 3.0 BY