Requesting a work item promotion

You can request a work item promotion from the Team Artifacts view. When you request a promotion, you can select one or more work items with change sets to promote.

1. In the Team Artifacts view, expand the project area folder.
2. Expand the Enterprise Extensions node, expand Promotions, right-click a promotion definition, and select Promote Work Items.
3. Optional: From the Promote Work Items wizard, to change the build options for your promotion, click Customize. The Customize Build Options wizard opens.
   Note: The Customize option is only available if you are promoting source and outputs.
   1. To change the build engine for the promotion, expand the Build Options section and specify a supporting build engine.
   2. To change the user that is associated with the build agent, expand the Build Agent Authentication Override section and enter a user name and password.
      Note: The promotion build engine must connect with the same user ID that is used in the Build Agent Authentication Override section of the dependency build.
   3. To run a preview build, expand the Promotion Build Options section and select the Preview build check box.
4. In the Promotion options section, select whether to promote only source or source and output.
   1. To include child work items for promotion, select Include children of selected work items.
   2. To include change sets that are ignored during a dependency build, select the Consider ignored changes check box.
      Note: If the change sets you are promoting contain files that were marked to be ignored by using the Ignore changes during dependency build option, you can use the Consider ignored changes option to override the original choice. Select the Consider ignored changes option to promote the ignored files even if the file states are not correct.
   3. To promote files that are affected by the changes that you are promoting, select the Include impacted outputs check box. After you complete the selections on this page, and click Next, the Impacted buildable files page opens with a list of the affected files to include in the promotion. You can move any files from the included files list to exclude them.
5. In the Select Work Items table, add the work items to promote to the table. Click Add or Run Query to select work items.
6. To view a summary of the promotion build request, select the Open summary work item check box and click Next.
   Note: To configure the summary work item or disable it, go to the Process Configuration tab of the project area and expand the Project Configuration, Project Configuration Data, and Promotion nodes.
7. On the Change set analysis page, the promotion process checks for gaps in the source code. If a gap is detected, a list of work items is displayed. You can select the work items in the list to include them in the promotion and continue or click View in Change Explorer to evaluate whether to include the changes in the promotion. You can run a promotion preview to generate a report that includes information about the gaps. If you do not want to include the changes in the promotion, click Cancel.
   For more information about gaps, see:

   • Merging change sets that contain gaps in history
   • Improved gap handling for SCM
8. The Work Item Summary page lists the work items that are selected for promotion and the change sets associated with each of those work items. Click Next.
9. To check for errors before the promotion build runs, request a promotion preview from the Promotion Preview page by clicking Run Preview.
   Note: Nothing is promoted when you click Run Preview.
   1. Click View Output to open the preview Promotion Build Report window.
   2. To save the promotion build report on your file system, click Export Output and select where to save the report.
10. To request the promotion, click Finish.
    A list of recent promotion results is displayed.
11. Find the promotion with the time stamp that matches your promotion.
    A preview promotion includes (Preview) in the label.
12. Double-click the promotion result.
    The promotion results editor opens.
13. Click either the Downloads tab or the External Links tab and click the links to open the promotionInfo.xml file or the promotionReport.xml file. If you requested a preview build, the promotionInfo.xml file lists the files that will be promoted when you run the promotion.

    promotionInfo.xml

    This input file for the promotion process indicates which output files and source build maps to copy to the target location during the promotion. In a promotion preview, the promotionInfo.xml file lists the output files and source build maps that will be promoted when the promotion runs.

    promotionReport.xml

    This output file that is generated by the promotion process lists the links to the build maps that were promoted to the target location during a promotion build. The report is empty if no build maps are promoted. A promotionReport.xml file is not generated in a promotion preview.